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

# プラグイン API リファレンス
<a name="sbomgen-plugin-api-reference"></a>

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

## 概要
<a name="sbomgen-plugin-api-reference-overview"></a>

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

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

### サンドボックスの制限
<a name="sbomgen-plugin-api-reference-sandbox-restrictions"></a>

 プラグインは、標準ライブラリへのアクセスが制限されたサンドボックス化された 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.\*関数を経由する必要があります (「」を参照)[ファイルアクセスの境界](#sbomgen-plugin-api-reference-file-access-boundary)。 | 
| os | システムレベルのオペレーション (os.execute、os.remove、os.rename、 os.getenvなど) は、プラグインがホストシステムを変更できないようにブロックされます。 | 
| debug | デバッグライブラリは、Lua VM 内部の検査や変更を防ぐためにブロックされます。 | 
| coroutine | コルーチンはロードされません。 | 

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

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

## プラグインライフサイクルグローバル
<a name="sbomgen-plugin-api-reference-plugin-lifecycle-globals"></a>

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

### 検出プラグイン
<a name="sbomgen-plugin-api-reference-discovery-plugins"></a>


| **関数** | **配列** | **必須** | **デフォルト (省略した場合)** | **説明** | 
| --- | --- | --- | --- | --- | 
| 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 スキャンについてのみ相談されます。 | 

### コレクションプラグイン
<a name="sbomgen-plugin-api-reference-collection-plugins"></a>


| **関数** | **配列** | **必須** | **デフォルト (省略した場合)** | **説明** | 
| --- | --- | --- | --- | --- | 
| 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
<a name="sbomgen-plugin-api-reference-file-i-o"></a>

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

### ファイルアクセスの境界
<a name="sbomgen-plugin-api-reference-file-access-boundary"></a>

 `sbomgen.*` ファイル関数は、インベントリ内のアーティファクトに読み取りを制限します。`../` トラバーサル経由など、アーティファクトルートの外部で解決されるパスは拒否され、呼び出しはホストファイルシステムを読み取るのではなくエラーを返します。これは`read_file`、、`open_file`、`read_dir``file_stat`、、およびパスを取るバイナリ/ハッシュヘルパーに適用されます。

 例外は、ホスト自体をインベントリする`localhost`アーティファクトタイプです。ホストファイルシステムはアーティファクトであるため、読み取りはより狭いルートに制限されません。

 この境界は、ファイルの*読み取り*のみを管理します。プラグインが SBOM に書き込む内容は制限されません。「」を参照してください[SBOM の内容がサニタイズされていない](#sbomgen-plugin-api-reference-sbom-contents-not-sanitized)。

### `sbomgen.get_file_list()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-file-list"></a>

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

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


| **関数** | **次の場合に使用します。** | 
| --- | --- | 
| sbomgen.find\_files\_by\_name() | 一致する正確なファイル名 (例: 、) "requirements.txt"がわかっている (例: "curl") | 
| sbomgen.find\_files\_by\_name\_icase() | 上記と同じですが、大文字と小文字は区別されません | 
| sbomgen.find\_files\_by\_suffix() | パスサフィックス (例: 、"curlver.h") "/pom.properties"を一致させる必要があります | 
| sbomgen.find\_files\_by\_path\_regex() | フルパス正規表現マッチングが必要です | 
| sbomgen.glob\_find\_files() | glob 形式のベースネームマッチングが必要です | 
これらの関数は Lua VM の外部でマッチングを実行し、マッチングされたパスのみを返し、300K-fileアーティファクトでも 1 ミリ秒未満で完了します。一致するロジックを上記のいずれでも表現できない`get_file_list()`場合にのみ使用します。  
`find_files_by_*` および `glob_find_files`ヘルパーはシンボリックリンクをスキップし、具体的なファイルのみを返すため、シンボリックリンクエイリアスとそのターゲットの両方がインベントリ化されません。 はシンボリックリンクを含むすべてのエントリ`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)`
<a name="sbomgen-plugin-api-reference-sbomgen-read-file-path"></a>

 ファイルの内容全体を読み取り、文字列として返します。
+ **戻り値:** `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)`
<a name="sbomgen-plugin-api-reference-sbomgen-open-file-path"></a>

 ストリーミング読み取り用の ファイルを開きます。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)`
<a name="sbomgen-plugin-api-reference-sbomgen-glob-find-files-pattern"></a>

 Go glob `filepath.Match` パターンに一致するファイルを返します。パターンはベースファイル名と照合されます。Symlink はスキップされ、具体的なファイルのみが返されます。
+ **戻り値:** `{string, ...}, err`

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

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

### `sbomgen.find_files_by_name(names)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-name-names"></a>

 ベース名 (最後のパスコンポーネント) が指定された名前の 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-name-icase-names"></a>

 ベース名が指定された名前の 1 つと一致するファイルを返します。大文字と小文字は無視されます。たとえば、 は `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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-suffix-suffixes"></a>

 完全 (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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-path-regex-patterns"></a>

 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`
<a name="sbomgen-plugin-api-reference-performance-find-files-by-vs-get-file-list"></a>

 検出プラグインの場合は、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)`
<a name="sbomgen-plugin-api-reference-sbomgen-read-dir-path"></a>

 ディレクトリ内のエントリを一覧表示します。
+ **戻り値:** `{{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)`
<a name="sbomgen-plugin-api-reference-sbomgen-file-stat-path"></a>

 ファイルに関するメタデータを返します。
+ **戻り値:** `{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)`
<a name="sbomgen-plugin-api-reference-sbomgen-read-zip-entry-path-entry-path"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-search-binary-path-regex"></a>

 ファイルを 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])`
<a name="sbomgen-plugin-api-reference-sbomgen-search-binary-all-path-regex-n"></a>

 ファイルを 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-search-binary-raw-path-regex"></a>

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

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

## FileHandle メソッド
<a name="sbomgen-plugin-api-reference-filehandle-methods"></a>

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

### `fh:read_line()`
<a name="sbomgen-plugin-api-reference-fh-read-line"></a>

 次の行を読み取ります (改行文字なし）。EOF `nil`で を返します。
+ **戻り値:** `string|nil, err`

### `fh:read(n)`
<a name="sbomgen-plugin-api-reference-fh-read-n"></a>

 最大`n`バイトまで読み取ります。EOF `nil`で を返します。
+ **戻り値:** `string|nil, err`

### `fh:close()`
<a name="sbomgen-plugin-api-reference-fh-close"></a>

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

## バイナリユーティリティ
<a name="sbomgen-plugin-api-reference-binary-utilities"></a>

### `sbomgen.hash(data, algorithm)`
<a name="sbomgen-plugin-api-reference-sbomgen-hash-data-algorithm"></a>

 指定されたアルゴリズムでメモリ内バイト文字列の 16 進エンコードされたダイジェストを返します。とペアリング`sbomgen.read_file(path)`して、解析用に既に読み込んだファイルをハッシュします。 `hash`はファイルを再読み込みしないため、バイトとダイジェストの両方`sbomgen.hash_file(path)`が必要な場合よりも優先されます。
+ **戻り値:** `string, err`
+ **アルゴリズム:** 許容されるアルゴリズム定数のリスト[コンポーネントハッシュ](#sbomgen-plugin-api-reference-component-hashes)については、「」を参照してください。

```
local data, err = sbomgen.read_file("/path/to/manifest.json")
if data then
    local sha256 = sbomgen.hash(data, sbomgen.hash_algorithms.SHA256)
    sbomgen.log_info("SHA-256: " .. sha256)
end
```

### `sbomgen.hash_file(path, algorithm)`
<a name="sbomgen-plugin-api-reference-sbomgen-hash-file-path-algorithm"></a>

 指定されたアルゴリズムでファイルの内容の 16 進エンコードされたダイジェストを返します。読み取りをアーティファクト I/O レイヤーにルーティングするため、ディレクトリ、コンテナ、アーカイブ、ボリューム、および localhost アーティファクト間で均一に動作します。これは、ダイジェストが ファイルに必要な唯一のものである場合に使用します。
+ **戻り値:** `string, err`

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

### `sbomgen.sha256(path)`
<a name="sbomgen-plugin-api-reference-sbomgen-sha256-path"></a>

**重要**  
 廃止済み。代わりに `sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)` を使用します。このエイリアスは下位互換性のために保持され、引き続き機能しますが、今後のリリースでは削除されます。アルゴリズムの選択が明示的`hash_file`になるように、新しいプラグインは を呼び出す必要があります。

 `sbomgen.hash_file(path, "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)`
<a name="sbomgen-plugin-api-reference-sbomgen-contains-bytes-path-patterns"></a>

 ファイルに指定された各バイトパターンが含まれているかどうかを確認します。入力パターンと同じ順序でブール値のテーブルを返します。
+ **戻り値:** `{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)`
<a name="sbomgen-plugin-api-reference-sbomgen-get-pe-version-info-path"></a>

 バイナリファイルから 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`、`ProductName``FileDescription`、 など) から描画された名前と値のペアのテーブルにマッピングされます。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)`
<a name="sbomgen-plugin-api-reference-sbomgen-parse-product-version-path"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-parse-file-version-path"></a>

 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
```

## パッケージ出力
<a name="sbomgen-plugin-api-reference-package-output"></a>

### `sbomgen.push_package(pkg)`
<a name="sbomgen-plugin-api-reference-sbomgen-push-package-pkg"></a>

 パッケージの検出結果を 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 プロパティ](#sbomgen-plugin-api-reference-cyclonedx-properties)) | 
| hashes | テーブル | いいえ | アルゴリズム名でキー指定されたコンポーネントハッシュ。「」を参照してください。 [コンポーネントハッシュ](#sbomgen-plugin-api-reference-component-hashes) | 
| 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",
    },
    hashes = {
        [sbomgen.hash_algorithms.SHA256] = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
    },
})
```

## コンポーネントハッシュ
<a name="sbomgen-plugin-api-reference-component-hashes"></a>

 オプションの `hashes`フィールドは、コンポーネントの整合性ダイジェスト`sbomgen.push_package()`を記録します。エントリはアルゴリズム名によってキー入力され、Amazon Inspector が想定するスキーマと一致する CycloneDX `components[].hashes`配列にシリアル化されます。

### サポートされているアルゴリズム
<a name="sbomgen-plugin-api-reference-component-hashes-supported-algorithms"></a>

 / に渡されるアルゴリズム名が `sbomgen.hash()` で受け入れられる`sbomgen.hash_file()`のと同じ文字列`sbomgen.hash_algorithms`になるように、 の定数を使用します`push_package({ hashes = ... })`。


| **定数** | **値** | **16 進ダイジェストの長さ** | 
| --- | --- | --- | 
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" | 40 | 
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" | 64 | 

### 検証ルール
<a name="sbomgen-plugin-api-reference-component-hashes-validation-rules"></a>

 `push_package()` は、検出結果を発行`hashes`する前に検証します。ハッシュ失敗の検証が削除され、警告がログに記録されるパッケージ。検証: 
+ アルゴリズム名は のエントリと一致する必要があります `sbomgen.hash_algorithms` (大文字と小文字が区別され、正確に `"SHA-1"`または `"SHA-256"`)。
+ 値は空でない小文字の 16 進数である必要があります。
+ 値はアルゴリズムの正しい長さである必要があります (SHA-1 の場合は 40 文字、SHA-256 の場合は 64 文字）。
+ 検証は再帰的です。内部の不正な形式のハッシュはパッケージ全体`children[].hashes`を拒否します。

### 例: マニフェストをハッシュし、ダイジェストをアタッチする
<a name="sbomgen-plugin-api-reference-component-hashes-example"></a>

```
function collect(file_path)
    local data, err = sbomgen.read_file(file_path)
    if err then return end

    local sha256 = sbomgen.hash(data, sbomgen.hash_algorithms.SHA256)

    sbomgen.push_package({
        name = "skill-manifest",
        version = "1.0.0",
        purl_type = "generic",
        component_type = sbomgen.component_types.DATA,
        hashes = {
            [sbomgen.hash_algorithms.SHA256] = sha256,
        },
    })
end
```

 ダイジェストがファイルから必要な唯一のものである場合は、ファイルを 2 回読み取る`sbomgen.hash_file(path, algo)`よりも優先します。1 回のパスで読み取りをアーティファクト I/O レイヤーにルーティングします。

## CycloneDX プロパティ
<a name="sbomgen-plugin-api-reference-cyclonedx-properties"></a>

 CycloneDX プロパティは、SBOM のコンポーネントにアタッチされたキーと値のメタデータです。これらは PURL 修飾子とは異なります。
+ **`qualifiers`** — PURL 修飾子。これらはパッケージ URL 文字列の一部になります (例: `pkg:deb/debian/curl@7.88.1?arch=amd64`)。一部の PURL 修飾子は Amazon Inspector に意味的意味を持ち、脆弱性の識別に影響します。[「パッケージ URL とは」を参照してください。](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html) for Inspector のタイプごとの規則。
+ **`properties`** — CycloneDX コンポーネントのプロパティ。これらは SBOM の`components[].properties`配列に表示され、コンポーネントの識別方法は変更されません。

### 予約済み名前空間
<a name="sbomgen-plugin-api-reference-reserved-namespaces"></a>

 CycloneDX プロパティ名前空間の `amazon:inspector:*`ファミリーは、Amazon Inspector 用に予約されています。
+ `amazon:inspector:sbom_generator:*` — sbomgen とその組み込みスキャナーによって使用されます。
+ `amazon:inspector:sbom_scanner:*` — Amazon Inspector スキャン API によって使用されます。

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

### キー命名規則
<a name="sbomgen-plugin-api-reference-key-naming-rules"></a>

 に渡されたプロパティキー`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 によって設定されたプロパティ
<a name="sbomgen-plugin-api-reference-properties-set-by-sbomgen"></a>

 Sbomgen は、出力するすべてのコンポーネントに独自のプロパティをアタッチできます。これらの値は予約済み`amazon:inspector:sbom_generator:*`名前空間から取得されるため、プラグインで生成しないでください。観測されたランタイム動作: 
+ `source_path` は常に sbomgen によって追加されます。
+ `source_file_scanner` と `source_package_collector`は、 `--enable-debug-props` が有効になっている場合に追加されます。

 予約キーの完全な分類は、Amazon Inspector ユーザーガイド: [ Amazon Inspector での CycloneDX 名前空間の使用](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html)」で管理されています。

### SBOM の内容がサニタイズされていない
<a name="sbomgen-plugin-api-reference-sbom-contents-not-sanitized"></a>

 Sbomgen は、プラグインが出力するデータを検査またはフィルタリングしません。コンポーネント名、バージョン、PURLs、ハッシュ、プロパティ値は、指定されたとおりに SBOM に書き込まれます。 Sbomgen はシークレット、認証情報、トークン、またはその他の機密データを検出または編集しません。プラグインがそのような値を検出結果に配置すると、出力 SBOM に表示され、SBOM が公開される場所を移動します。

 プラグインが書き込む内容は、お客様の責任となります。インベントリするアーティファクトから派生したデータのみを出力し、含めるものを決定するときに SBOM を共有可能なアーティファクトとして扱います。

## プロパティ定数
<a name="sbomgen-plugin-api-reference-property-constants"></a>

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

 カスタムプラグインの作成者は、これらの定数を再利用するのではなく、独自の名前空間 ( など`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 | 

## スキャナーグループ
<a name="sbomgen-plugin-api-reference-scanner-groups"></a>

 検出プラグインは、 を介してスキャナーグループを宣言する必要があります`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
```

## コンポーネントタイプの定数
<a name="sbomgen-plugin-api-reference-component-type-constants"></a>

 の `component_type`フィールドは、CycloneDX 1.5 コンポーネントタイプの 1 つ`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,
})
```

## ハッシュアルゴリズム定数
<a name="sbomgen-plugin-api-reference-hash-algorithm-constants"></a>

 、`sbomgen.hash()`、`sbomgen.hash_file()`および の `hashes`フィールドのアルゴリズムパラメータの定数`sbomgen.push_package()`。文字列値は CycloneDX ハッシュアルゴリズム名と一致するため、同じ定数が変換なしでハッシュパス全体を通過します。


| **定数** | **値** | 
| --- | --- | 
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" | 
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" | 

 例: 

```
local digest = sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)
sbomgen.push_package({
    name = "example",
    purl_type = "generic",
    component_type = sbomgen.component_types.LIBRARY,
    hashes = { [sbomgen.hash_algorithms.SHA256] = digest },
})
```

## プラットフォーム定数
<a name="sbomgen-plugin-api-reference-platform-constants"></a>

 と を比較するための定数`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
```

## アーティファクト情報
<a name="sbomgen-plugin-api-reference-artifact-info"></a>

### `sbomgen.get_platform()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-platform"></a>

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

### `sbomgen.get_artifact_type()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-artifact-type"></a>

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

### `sbomgen.should_collect_licenses()`
<a name="sbomgen-plugin-api-reference-sbomgen-should-collect-licenses"></a>

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

### `sbomgen.get_env_vars()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-env-vars"></a>

 アーティファクトから環境変数を`{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()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-system-drive"></a>

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

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

### `sbomgen.resolve_glob_paths(patterns)`
<a name="sbomgen-plugin-api-reference-sbomgen-resolve-glob-paths"></a>

 ホストファイルシステムに対してファイルシステムの glob パターンを拡張します。Localhost-only: 他のアーティファクトタイプでエラー`nil`を加算して返します。

```
function get_localhost_scan_paths()
    return sbomgen.resolve_glob_paths({
        "/home/*/.cache/huggingface/hub",
        "/Users/*/.cache/huggingface/hub",
        "C:/Users/*/.cache/huggingface/hub",
    })
end
```

 **動作:** 
+ パターン構文は Go の [https://pkg.go.dev/path/filepath#Match](https://pkg.go.dev/path/filepath#Match): `*`、`?`、`[abc]`、 に従います`[a-z]`。
+ 入力パターンと出力パスは正規化されます。冗長区切り文字 (`a//b`)、ドットセグメント (`a/./b`)、末尾の区切り文字 (`a/b/`) は折りたたまれます。
+ 出力は重複排除され、パスの最初の出現が優先されます。入力パターンの順序は、結果全体で保持されます。
+ 何も一致しないパターンはエントリを返しません。空の文字列パターンはサイレントにスキップされます。不正な形式のパターン (括弧の不一致など) は警告を発し、スキップされます。

 **クロスプラットフォームパス区切り文字:** 
+ **すべてのパスにスラッシュ (`/`) を使用します。**フォワードスラッシュは Linux、macOS、および Windows で機能します。Go のファイルパスロジックはそれらを Windows のネイティブ区切り文字に変換します。
+ **バックスラッシュ区切り文字は Windows でのみ機能します。**Linux および macOS では、 `\`はパス区切り文字ではなくリテラルファイル名文字です。 のようなパターンは POSIX システムでは何も`"C:\\Users\\*"`一致しません。
+ **Lua 文字列のリテラル Windows スタイルのパスは避けてください。**は有効な Lua エスケープ`\U`ではない`C:<form-feed>sers`ため (、 `\t`など)`\f`、 のような Lua 文字列`"C:\Users"`は と解釈されるため`\n`、パターンはサイレントに失敗します。フォワードスラッシュ、エスケープバックスラッシュ (`"C:\\Users"`)、またはロングブラケットの raw 文字列 () を使用します`[[C:\Users]]`。

## システム情報
<a name="sbomgen-plugin-api-reference-system-info"></a>

 これらの関数は、アーティファクトのオペレーティングシステムとハードウェアに関するメタデータを返します。情報が利用できない場合 (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() | システムのホスト名 | 

## 正規表現
<a name="sbomgen-plugin-api-reference-regular-expressions"></a>

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

### `sbomgen.regex_find(str, pattern)`
<a name="sbomgen-plugin-api-reference-sbomgen-regex-find-str-pattern"></a>

 Go 正規表現パターンの最初の一致を返します。一致しない`nil`場合は を返します。
+ **戻り値:** `string|nil, err`

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

### `sbomgen.regex_match(str, pattern)`
<a name="sbomgen-plugin-api-reference-sbomgen-regex-match-str-pattern"></a>

 最初の一致からキャプチャグループを返します。インデックス 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])`
<a name="sbomgen-plugin-api-reference-sbomgen-regex-find-all-str-pattern-n"></a>

 重複しないすべての一致を返します。を渡`n`して結果を制限します (デフォルト: すべて）。
+ **戻り値:** `{string, ...}|nil, err`

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

### `sbomgen.regex_replace(str, pattern, replacement)`
<a name="sbomgen-plugin-api-reference-sbomgen-regex-replace-str-pattern-replacement"></a>

 すべての一致を置き換えます。置換文字列は`$1`、キャプチャグループの参照に `$2`、 などを使用できます。
+ **戻り値:** `string, err`

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

### 正規表現パターンと Lua パターンを使用するタイミング
<a name="sbomgen-plugin-api-reference-when-to-use-regex-vs-lua-patterns"></a>

 Lua の組み込み `string.match`/`string.find` はシンプルなパターンに使用します。高速で、バックスラッシュをエスケープする必要はありません。`sbomgen.regex_*` 必要に応じて を使用します。
+ 代替: `(foo|bar)`
+ 量子範囲: `\d{8,}`
+ Lua パターンでは表現できない複雑な文字クラス

## 構造化解析
<a name="sbomgen-plugin-api-reference-structured-parsing"></a>

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

### `sbomgen.json_decode(str)`
<a name="sbomgen-plugin-api-reference-sbomgen-json-decode-str"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-xml-decode-str"></a>

 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 レジストリ
<a name="sbomgen-plugin-api-reference-windows-registry"></a>

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

### `sbomgen.registry_open_key(path)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-open-key-path"></a>

 レジストリキーを開きます。で閉じる必要があるキーハンドルを返します`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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-string-key-value-name"></a>

 開いているレジストリキーから文字列値を読み取ります。
+ **戻り値:** `string, err`

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

### `sbomgen.registry_get_integer(key, value_name)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-integer-key-value-name"></a>

 開いているレジストリキーから整数値を読み取ります。
+ **戻り値:** `number, err`

### `sbomgen.registry_get_strings(key, value_name)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-strings-key-value-name"></a>

 開いているレジストリキーからマルチ文字列 (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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-subkeys-key"></a>

 開いているレジストリキーの下にすべてのサブキー名を返します。
+ **戻り値:** `{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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-close-key"></a>

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

## ログ記録
<a name="sbomgen-plugin-api-reference-logging"></a>

 ログメッセージは 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))
```

## 関数のデバッグ
<a name="sbomgen-plugin-api-reference-debugging-functions"></a>

### `sbomgen.breakpoint(message)`
<a name="sbomgen-plugin-api-reference-sbomgen-breakpoint-message"></a>

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

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

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

## API のテスト
<a name="sbomgen-plugin-api-reference-testing-api"></a>

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

### スキャン関数
<a name="sbomgen-plugin-api-reference-scan-functions"></a>

 各スキャン関数は、特定の種類のアーティファクトを作成し、それに対して現在のプラグインの検出→収集パイプラインを実行し、結果を返します。`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 つすべての は、以下のシェイプの結果テーブルを返します。

### 結果シェイプ
<a name="sbomgen-plugin-api-reference-result-shape"></a>

 各検出結果テーブルは、以下に示すフィールドのみを射影します。特に、 `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)
```

### アサーション
<a name="sbomgen-plugin-api-reference-assertions"></a>


| **関数** | **署名** | **説明** | 
| --- | --- | --- | 
| 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。 | 

### コントロールフロー
<a name="sbomgen-plugin-api-reference-control-flow"></a>


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

### 検出のテスト
<a name="sbomgen-plugin-api-reference-test-discovery"></a>

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

## エラー処理
<a name="sbomgen-plugin-api-reference-error-handling"></a>

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