外掛程式 API 參考

完成 inspector-sbomgen Lua 外掛程式的 API 參考。如需撰寫外掛程式的指南，請參閱 外掛程式開發人員指南。如需測試，請參閱 外掛程式測試指南。

概觀

所有執行時間提供的函數都可以透過全域sbomgen資料表 （檔案 I/O、regex、記錄、常數等） 存取。此外，每個外掛程式都會定義一組最上層全域函數 (discover、subscribe_to_event、、 等）， sbomgen collect get_scanner_name會在外掛程式生命週期中定義的點呼叫。這些會記錄在 中外掛程式生命週期全域。

在*_test.lua檔案內，sbomgen 還會公開testing全域，讓測試作者驅動 探索→集合管道並進行宣告。請參閱 測試 API。

沙盒限制

外掛程式會在沙盒化 Lua VM 中執行，並限制標準程式庫存取。下列 Lua 標準程式庫模組可供使用：

模組	備註
base	核心函數 (print、type、tostring、tonumberpairs、、ipairs、pcallerror、selectunpack、、rawget、rawset、 等）。dofile、 loadfile和 loadstring會移除。
string	完整字串操作 (string.match、string.findstring.format、、 string.gsub等）
table	完整資料表處理 table.remove(table.insert、table.sort、、 table.concat等）
math	完整數學程式庫 (math.floor、math.min、 math.max等）
package	require() 可供使用，但僅限於外掛程式本身目錄樹狀目錄中的模組。父目錄周遊 (require("../shared")) 已封鎖。 package.cpath和 package.path已清除。

基於安全性和穩定性，明確不允許下列標準程式庫模組：

模組	原因
io	直接檔案系統存取已封鎖。所有檔案操作都必須經過 sbomgen.*函數，這些函數會透過成品界面路由，跨成品類型 （目錄、容器、磁碟區等） 實現一致的行為。
os	系統會封鎖系統層級操作 os.remove(os.execute、os.rename、os.getenv、 等），以防止外掛程式修改主機系統。
debug	偵錯程式庫會遭到封鎖，以防止 Lua VM 內部的檢查或修改。
coroutine	不會載入 Coroutine。

這些模組不在 VM 的允許清單中，且無法由外掛程式存取。

注意

重要：所有檔案 I/O 必須通過 sbomgen.*函數 sbomgen.read_file（例如 、sbomgen.open_file、sbomgen.get_file_list)。使用 io.open或任何直接檔案系統存取都會引發執行時間錯誤。sbomgen API 可確保外掛程式與成品抽象層互動，無論掃描目錄、容器映像、封存或磁碟區，都能提供一致的行為。

外掛程式生命週期全域

外掛程式是名為 的 Lua 檔案init.lua，可定義特定最上層全域函數。這些全域不在sbomgen資料表中 — 這些是外掛程式為 sbomgen 定義的函數。探索外掛程式和集合外掛程式之間的有效全域集不同。對於以下每個函數，如果外掛程式省略它，則會使用資料表中顯示的預設值。

探索外掛程式

函數	Arity	必要	預設 （省略時）	Description
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掃描。

集合外掛程式

函數	Arity	必要	預設 （省略時）	Description
collect(file_path)	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()	您知道要比對的確切檔案名稱 （例如 "requirements.txt"、) "curl"
sbomgen.find_files_by_name_icase()	與上述相同，但不區分大小寫
sbomgen.find_files_by_suffix()	您需要比對路徑尾碼 （例如 "/pom.properties"、 "curlver.h")
sbomgen.find_files_by_path_regex()	您需要全路徑 regex 比對
sbomgen.glob_find_files()	您需要 glob 樣式的 basename 比對

這些函數會在 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 filepath.Match glob 模式的檔案。模式會與基本檔案名稱相符。

• 傳回： {string, ...}, err

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

使用 sbomgen.get_file_list()搭配 string.match進行完整路徑模式比對。

sbomgen.find_files_by_name(names)

傳回基底名稱 （最後一個路徑元件） 完全符合其中一個指定名稱的檔案。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) regex 模式的檔案。比對發生在 Lua VM 之外，這使得大型檔案清單更有效率。

• 參數： patterns — Go regex 字串的資料表

• 傳回：{string, ...}— 相符的檔案路徑 （無錯誤元組）

• 引發：如果任何模式無法編譯，Lua 錯誤

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

效能： find_files_by_* vs get_file_list

對於探索外掛程式，偏好 find_files_by_name、 find_files_by_suffix或 ，find_files_by_path_regex而不是在 Lua get_file_list()中反覆運算。在具有 300K 檔案的 localhost 掃描上，使用 在 Lua 中重複檔案清單string.match()大約需要 15 秒，而在 1 毫秒內find_files_by_name完成。差別在於， 會將每個檔案路徑get_file_list()複製到 Lua VM 做為字串，然後 Lua 會解譯每個路徑的迴圈和模式比對。find_files_by_* 函數會在 Lua VM 之外執行相符項目，並僅傳回相符路徑，避免複製和每個路徑的解釋額外負荷。

get_file_list() 只有當您需要無法以 basename、尾碼或 regex 比對表示的自訂比對邏輯時，才使用 。

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 封存檔讀取單一項目。

• 傳回： 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 regex 比對。

• 傳回：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)

搜尋整個二進位檔案以進行第一個 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)

傳回檔案內容的十六進位編碼 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、FileDescription、 ProductName等） 繪製的名稱/值對資料表。PE 二進位檔可能會公開一或多個地區設定。

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 資料表支援下列欄位：

欄位	類型	必要	Description
name	string	是	套件名稱
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？ 適用於 Inspector 的每種類型慣例。

• properties — CycloneDX 元件屬性。這些會出現在 SBOM 的components[].properties陣列中，不會變更元件的識別方式。

預留命名空間

CycloneDX 屬性命名空間amazon:inspector:*系列保留給 Amazon Inspector：

• amazon:inspector:sbom_generator:* — 供 sbomgen 及其內建掃描器使用。

• amazon:inspector:sbom_scanner:* — 由 Amazon Inspector Scan API 使用。

外掛程式定義的屬性不得使用這些命名空間。寫入預留命名空間可能會與 Inspector 依賴的值陰影或衝突，而產生的 SBOM 可能會在漏洞識別期間被錯誤解譯。如需預留金鑰的完整清單，請參閱搭配 Amazon Inspector 使用 CycloneDX 命名空間。

金鑰命名規則

傳遞給 sbomgen.push_package() 的屬性金鑰處理方式如下：

輸入金鑰	SBOM 中產生的金鑰	建議用於自訂外掛程式？
包含 :（例如 acme:my_plugin:field)	逐字使用	是 — 將每個外掛程式定義的屬性放在您自己的命名空間中
否 :（例如 field)	自動字首為 amazon:inspector:sbom_generator:field	否 — 這會寫入預留命名空間

一律在您定義的屬性索引鍵中包含至少一個冒號。使用組織或外掛程式獨有的命名空間 （例如 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 命名空間。

屬性常數

內建屬性金鑰常數可透過 取得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：

常數	Value	Description
sbomgen.groups.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 欄位push_package()必須是 CycloneDX 1.5 元件類型之一。常數可透過 取得sbomgen.component_types：

常數	Value
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：

常數	Value
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()

傳回執行時間平台字串 "linux"（例如 、"windows"、"darwin")。

sbomgen.get_artifact_type()

傳回要掃描的成品類型 （例如 "directory"、 "archive")。

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:"若未設定，預設為 。這是相當於 的 Luastrutils.GetSystemDriverLetter()。

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

系統資訊

這些函數會傳回成品作業系統和硬體的相關中繼資料。如果資訊不可用 （例如，掃描沒有作業系統中繼資料的目錄時），值可能是空字串。

函數	傳回值
sbomgen.get_os_name()	作業系統名稱 （例如 "Ubuntu"、"Alpine Linux")
sbomgen.get_os_version()	作業系統版本 （例如 "22.04"、"3.18")
sbomgen.get_os_codename()	作業系統程式碼名稱 （例如，"jammy"、"bookworm")
sbomgen.get_os_id()	作業系統識別符 （例如 "ubuntu"、"alpine")
sbomgen.get_kernel_name()	核心名稱 （例如 "Linux")
sbomgen.get_kernel_version()	核心版本字串
sbomgen.get_cpu_arch()	CPU 架構 （例如 "x86_64"、"aarch64")
sbomgen.get_hostname()	系統的主機名稱

一般表達式

Lua 的內建模式缺少輪換 (|)、量化器範圍 ({n,}) 和 lookahead 等功能。為了縮小此差距，sbomgen 會直接公開 Go 的regexp套件。這些函數使用 Go regex 語法 (RE2)，而不是 Lua 模式。

sbomgen.regex_find(str, pattern)

傳回 Go regex 模式的第一個相符項目，或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.*)$", "")

何時使用 regex 與 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 hive 剖析 （容器/磁碟區掃描）。

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一律列印。 log_debug只會在使用 叫用 sbomgen 時列印--verbose。

函數	關卡	預設可見？
sbomgen.log_debug(message)	DEBUG	否 — 需要 --verbose
sbomgen.log_info(message)	INFO	是
sbomgen.log_warn(message)	WARN	是
sbomgen.log_error(message)	ERROR	是

將 string.format用於格式化訊息：

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

偵錯 函數

sbomgen.breakpoint(message)

列印message到 stderr 並封鎖執行，直到使用者按下 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.read_file()) 的sbomgen.*函數只會在從掃描內呼叫時產生有意義的結果。如需敘述性指南，請參閱 外掛程式測試指南。

掃描函數

每個掃描函數都會建立指定類型的成品，針對該成品執行目前外掛程式的 探索→集合管道，並傳回結果調查結果。引path數會相對於測試檔案的目錄解析。

函數	成品種類
testing.scan_directory(path)	目錄
testing.scan_archive(path)	目錄 ( 的別名scan_directory)
testing.scan_localhost(path)	Localhost
testing.scan_binary(path)	二進位
testing.scan_volume(path)	磁碟區
testing.scan_container(path)	容器

這六個都會傳回形狀如下的結果資料表。

結果形狀

每個問題清單資料表只會投影下列欄位。特別是， 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)

聲明

函數	Signature	Description
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)	如果 haystack 不包含 needle（子字串比對），則失敗。
testing.assert_matches	(str: string, pattern: string, message?: string)	如果 str 不符合指定的 Go (RE2) regex，則失敗。
testing.assert_length	(tbl: table, expected: integer, message?: string)	如果 #tbl 不等於 ，則失敗expected。

控制流程

函數	Signature	Description
testing.fail	(message: string)	使用指定的訊息立即失敗目前的測試。
testing.skip	(message: string)	略過目前的測試。結果會回報為略過，而非失敗。

測試探索

名稱在檔案比對test_中以 開頭的任何全域 Lua 函數*_test.lua都會視為測試。測試檔案必須位於正常{phase}/{platform}/{category}/{ecosystem}/深度init.lua的 旁。修正資料會傳入測試檔案_testdata/旁 - 執行器在搜尋測試檔案_testdata/時不會下降至 。

錯誤處理

可能失敗的 API 函數會傳回兩個值：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 會記錄警告並繼續下一個檔案或外掛程式。其他外掛程式不受影響。