Referensi API Plugin

Referensi API lengkap untuk plugin Lua inspector-sbomgen. Untuk panduan menulis plugin, lihatPanduan pengembang plugin. Untuk pengujian, lihatPanduan pengujian plugin.

Ikhtisar

Semua fungsi yang disediakan runtime diakses melalui sbomgen tabel global (file I/O, regex, logging, konstanta, dll.). Selain itu, setiap plugin mendefinisikan satu set kecil fungsi global tingkat atas (discover,,,, collect get_scanner_namesubscribe_to_event, dan sebagainya) yang dipanggil sbomgen pada titik yang ditentukan dalam siklus hidup plugin. Ini didokumentasikan dalamPlugin Siklus Hidup Global.

Di dalam *_test.lua file, sbomgen juga mengekspos testing global yang memungkinkan penulis pengujian mendorong pipeline penemuan→pengumpulan dan membuat pernyataan. Lihat Pengujian API.

Pembatasan Kotak Pasir

Plugin berjalan di VM Lua kotak pasir dengan akses perpustakaan standar terbatas. Modul perpustakaan standar Lua berikut tersedia:

Modul	Catatan
base	Fungsi inti (print,type,tostring,tonumber,pairs, ipairspcall,error,select,unpack,rawget,rawset, dll.). dofile,loadfile, dan loadstring dihapus.
string	Manipulasi string penuh (string.matchstring.find,string.format,string.gsub,, dll.)
table	Manipulasi meja penuh (table.inserttable.remove,table.sort,table.concat,, dll.)
math	Perpustakaan matematika lengkap (math.floor,math.max,math.min, dll.)
package	require()tersedia tetapi terbatas pada modul di dalam pohon direktori plugin itu sendiri. Parent-directory traversal (require("../shared")) diblokir. package.cpathdan package.path dibersihkan.

Modul pustaka standar berikut secara eksplisit tidak diizinkan untuk keamanan dan stabilitas:

Modul	Alasan
io	Akses sistem file langsung diblokir. Semua operasi file harus melalui sbomgen.* fungsi, yang merutekan melalui antarmuka artefak untuk perilaku yang konsisten di seluruh jenis artefak (direktori, wadah, volume, dll.).
os	Operasi tingkat sistem (os.execute,,,os.remove, os.renameos.getenv, dll.) Diblokir untuk mencegah plugin memodifikasi sistem host.
debug	Pustaka debug diblokir untuk mencegah inspeksi atau modifikasi internal Lua VM.
coroutine	Coroutine tidak dimuat.

Modul-modul ini tidak ada dalam daftar izin VM dan tidak dapat diakses oleh plugin.

catatan

Penting: Semua file I/O harus melalui sbomgen.* fungsi (misalnya,sbomgen.read_file,sbomgen.open_file,sbomgen.get_file_list). Menggunakan io.open atau akses sistem file langsung apa pun akan memunculkan kesalahan runtime. sbomgenAPI memastikan plugin berinteraksi dengan lapisan abstraksi artefak, yang memberikan perilaku yang konsisten baik memindai direktori, gambar kontainer, arsip, atau volume.

Plugin Siklus Hidup Global

Plugin adalah file Lua bernama init.lua yang mendefinisikan fungsi global tingkat atas tertentu. Global-global ini tidak ada di atas sbomgen meja — mereka adalah fungsi yang didefinisikan oleh plugin untuk dipanggil sbomgen. Kumpulan global yang valid berbeda antara plugin penemuan dan plugin koleksi. Untuk setiap fungsi di bawah ini, jika plugin menghilangkannya, default yang ditunjukkan dalam tabel digunakan.

Plugin penemuan

Fungsi	Arity	Diperlukan	Default (bila dihilangkan)	Deskripsi
discover()	0	Ya	—	Mengembalikan file plugin ini telah ditemukan. Kembalikan tabel sekuensial string jalur (mode acara tunggal) atau tabel yang dikunci oleh string nama peristiwa yang nilainya adalah tabel jalur (mode multi-acara).
get_event_name()	0	Tidak	"lua:{platform}/{category}/{ecosystem}"	Mengembalikan nama acara di mana file diterbitkan. Harus unik di semua plugin penemuan.
get_scanner_name()	0	Tidak	nama direktori ekosistem	Mengembalikan nama tampilan pemindai. Harus unik di semua plugin penemuan.
get_scanner_description()	0	Tidak	"Lua discovery plugin: {ecosystem}"	Mengembalikan deskripsi yang dapat dibaca manusia.
get_scanner_groups()	0	Tidak	Berasal dari direktori kategori (lihat panduan pengembang)	Mengembalikan tabel string grup scanner. Gunakan sbomgen.groups.* konstanta.
get_localhost_scan_paths()	0	Tidak	—	Mengembalikan tabel file/directory jalur untuk disertakan saat memindai artefak localhost. Hanya dikonsultasikan untuk localhost pemindaian.

Plugin koleksi

Fungsi	Arity	Diperlukan	Default (bila dihilangkan)	Deskripsi
collect(file_path)	1	Ya	—	Dipanggil sekali per file yang diterbitkan ke acara berlangganan. Mengurai file dan memancarkan temuan melalui. sbomgen.push_package() Tidak mengembalikan apa-apa.
subscribe_to_event()	0	Tidak	"lua:{platform}/{category}/{ecosystem}"	Mengembalikan nama acara kolektor ini berlangganan. Harus cocok dengan plugin penemuan yang sesuaiget_event_name().
get_collector_name()	0	Tidak	nama direktori ekosistem	Mengembalikan nama tampilan kolektor. Harus unik di semua plugin koleksi.
get_collector_description()	0	Tidak	""(kosong)	Mengembalikan deskripsi yang dapat dibaca manusia.

Berkas I/O

Semua operasi file harus melalui sbomgen.* API. Akses sistem file langsung melalui io pustaka Lua tidak tersedia (lihat). Pembatasan Kotak Pasir I/O Fungsi sbomgen file merutekan melalui antarmuka artefak, memastikan plugin Anda bekerja secara identik apakah memindai direktori pada disk, gambar kontainer, arsip terkompresi, atau volume yang dipasang.

sbomgen.get_file_list()

Mengembalikan semua jalur file dalam artefak sebagai tabel string.

• Pengembalian: {string, ...} — tabel string path file absolut

• Kinerja: Fungsi ini menyalin setiap path file dalam artefak ke dalam Lua VM sebagai string Lua. Pada artefak besar (misalnya, pemindaian localhost dengan file 300K +), ini saja membutuhkan beberapa detik. Mengulangi tabel yang dikembalikan di Lua dengan string.match() menambahkan overhead lebih lanjut - pemindaian penuh dapat memakan waktu 15+ detik. Semakin banyak file dalam artefak, semakin lambat plugin Anda.

catatan

Pilih alternatif yang ditargetkan ini bila memungkinkan:

Fungsi	Gunakan saat...
sbomgen.find_files_by_name()	Anda tahu nama file yang tepat untuk dicocokkan (mis.,,"requirements.txt") "curl"
sbomgen.find_files_by_name_icase()	Sama seperti di atas, tetapi tidak peka huruf besar/kecil
sbomgen.find_files_by_suffix()	Anda harus mencocokkan sufiks jalur (misalnya,,"/pom.properties") "curlver.h"
sbomgen.find_files_by_path_regex()	Anda membutuhkan pencocokan regex jalur lengkap
sbomgen.glob_find_files()	Anda membutuhkan pencocokan nama dasar gaya glob

Fungsi-fungsi ini melakukan pencocokan di luar VM Lua dan hanya mengembalikan jalur yang cocok, menyelesaikan dalam waktu kurang dari 1 milidetik bahkan pada artefak file 300K. Gunakan get_file_list() hanya ketika logika pencocokan Anda tidak dapat diekspresikan dengan salah satu di atas.

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

Membaca seluruh isi file dan mengembalikannya sebagai string.

• Pengembalian: string, err

• Pada kegagalan: 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)

Membuka file untuk streaming membaca. Mengembalikan FileHandle objek. Gunakan ini untuk file besar di mana memuat seluruh konten ke dalam memori tidak praktis.

• Pengembalian: 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)

Mengembalikan file yang cocok dengan pola Go filepath.Match glob. Pola dicocokkan dengan nama file dasar.

• Pengembalian: {string, ...}, err

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

Gunakan sbomgen.get_file_list() dengan string.match untuk pencocokan pola jalur lengkap.

sbomgen.find_files_by_name(names)

Mengembalikan file yang nama basename (komponen jalur terakhir) persis cocok dengan salah satu nama yang diberikan. Iterasi dan perbandingan terjadi di Go, membuat ini secara signifikan lebih cepat daripada iterasi sbomgen.get_file_list() di Lua.

• Parameter: names — tabel string (nama dasar yang cocok)

• Pengembalian: {string, ...} - jalur file yang cocok (tidak ada kesalahan tuple)

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)

Mengembalikan file yang nama dasarnya cocok dengan salah satu nama yang diberikan, mengabaikan kasus. Misalnya, "version" korek apiVERSION,Version, danversion. Sepertifind_files_by_name, pencocokan terjadi di luar VM Lua.

• Parameter: names — tabel string (nama dasar yang cocok, tidak peka huruf besar/kecil)

• Pengembalian: {string, ...} - jalur file yang cocok (tidak ada kesalahan tuple)

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)

Mengembalikan file yang full (forward-slash-normalized) path berakhir dengan salah satu sufiks yang diberikan. Sepertifind_files_by_name, pencocokan terjadi di luar VM Lua.

• Parameter: suffixes — tabel string (sufiks jalur untuk mencocokkan)

• Pengembalian: {string, ...} - jalur file yang cocok (tidak ada kesalahan tuple)

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)

Mengembalikan file yang forward-slash-normalized jalurnya cocok dengan pola regex Go (RE2) yang diberikan. Pencocokan terjadi di luar Lua VM, yang membuat ini efisien pada daftar file besar.

• Parameter: patterns — tabel string Go regex

• Pengembalian: {string, ...} - jalur file yang cocok (tidak ada kesalahan tuple)

• Menimbulkan: kesalahan Lua jika ada pola yang gagal dikompilasi

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

Kinerja: find_files_by_* vs get_file_list

Untuk plugin penemuan, pilih, find_files_by_namefind_files_by_suffix, atau find_files_by_path_regex lebih iterasi get_file_list() di Lua. Pada pemindaian localhost dengan 300K file, iterasi daftar file di Lua dengan string.match() waktu ~ 15 detik, sementara find_files_by_name selesai di bawah 1 milidetik. Perbedaannya adalah bahwa get_file_list() menyalin setiap jalur file ke Lua VM sebagai string, lalu Lua menafsirkan loop dan pola yang cocok untuk masing-masing. find_files_by_*Fungsi melakukan pencocokan di luar VM Lua dan hanya mengembalikan jalur yang cocok, menghindari overhead interpretasi salinan dan per-jalur.

Gunakan get_file_list() hanya ketika Anda membutuhkan logika pencocokan khusus yang tidak dapat dinyatakan sebagai nama dasar, akhiran, atau kecocokan regex.

sbomgen.read_dir(path)

Daftar entri dalam direktori.

• Pengembalian: {{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)

Mengembalikan metadata tentang file.

• Pengembalian: {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)

Membaca satu entri dari arsip ZIP, JAR, atau WAR.

• Pengembalian: string, err

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

sbomgen.search_binary(path, regex)

Mem-parsing file sebagai biner ELF, PE, atau Mach-O dan mencari constant/variable bagian default untuk kecocokan Go regex.

• Mengembalikan: string|nil, err - string cocok, atau nihil jika tidak cocok

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])

Mem-parsing file sebagai biner ELF, PE, atau Mach-O dan mengembalikan semua kecocokan grup tangkapan pertama yang unik dari bagian default. constant/variable Lulus n untuk membatasi hasil.

• Pengembalian: {string, ...}|nil, err — tabel string yang cocok, atau nihil jika tidak ada kecocokan

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)

Mencari seluruh file biner untuk kecocokan regex pertama, tidak terbatas pada bagian tertentu. Gunakan ketika pencarian berbasis bagian (search_binary) tidak mencukupi — misalnya, ketika string versi berada di bagian non-standar.

• Mengembalikan: string|nil, err - string cocok, atau nihil jika tidak cocok

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

FileHandle Metode

FileHandle objek dikembalikan olehsbomgen.open_file().

fh:read_line()

Membaca baris berikutnya (tanpa karakter baris baru). Kembali nil di EOF.

• Pengembalian: string|nil, err

fh:read(n)

Membaca hingga n byte. Kembali nil di EOF.

• Pengembalian: string|nil, err

fh:close()

Menutup pegangan file. Selalu tutup pegangan saat selesai.

Utilitas Biner

sbomgen.sha256(path)

Mengembalikan hash SHA-256 yang dikodekan hex-dari isi file.

• Pengembalian: 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)

Memeriksa apakah file berisi masing-masing pola byte yang diberikan. Mengembalikan tabel boolean dalam urutan yang sama dengan pola input.

• Pengembalian: {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)

Mem-parsing sumber daya versi Windows PE dari file biner. Mengembalikan tabel dengan bidang versi, atau nil, err jika file tersebut bukan biner PE atau tidak memiliki sumber daya versi.

• Pengembalian: {product_version, file_version, string_table}, err

file_versionBidang product_version dan berasal dari FixedFileInfo struktur PE, diformat sebagai"major.minor.build.revision". string_tableBidang adalah tabel bersarang yang dikunci oleh kode lokal (misalnya, "040904B0" untuk US English Unicode). Setiap lokal memetakan ke tabel name/value pasangan yang diambil dari PE StringFileInfo (ProductVersion,, ProductNameFileDescription, dll.). Biner PE dapat mengekspos satu atau lebih lokal.

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)

Pembungkus kenyamanan yang mengembalikan hanya string versi produk dari biner PE. FixedFileInfo Setara dengan menelepon get_pe_version_info(path) dan membacaproduct_version.

• Pengembalian: 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)

Pembungkus kenyamanan yang mengembalikan hanya string versi file dari biner PE. FixedFileInfo Setara dengan menelepon get_pe_version_info(path) dan membacafile_version.

• Pengembalian: string, err

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

Package Output

sbomgen.push_package(pkg)

Mendorong penemuan paket ke dalam SBOM. Hanya tersedia di plugin koleksi.

pkgTabel mendukung bidang-bidang berikut:

Bidang	Jenis	Diperlukan	Deskripsi
name	string	Ya	Nama paket
version	string	Tidak	String versi yang diselesaikan
namespace	string	Tidak	Namespace PURL (misalnya,,) "curl" "wordpress/plugin"
purl_type	string	Ya	Jenis PURL (misalnya,"pypi",,"npm", "cargo""deb","generic")
component_type	string	Ya	Jenis komponen CycloneDX; gunakan sbomgen.component_types.* konstanta (mis.,) sbomgen.component_types.LIBRARY
qualifiers	tabel	Tidak	Kualifikasi PURL sebagai pasangan nilai kunci (muncul di URL paket)
properties	tabel	Tidak	Properti komponen CycloneDX sebagai pasangan kunci-nilai (lihat) Properti CycloneDX
children	tabel	Tidak	Paket anak bersarang, masing-masing dengan bentuk yang sama seperti pkg (bidang wajib divalidasi secara rekursif)

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",
    },
})

Properti CycloneDX

Properti CycloneDX adalah metadata nilai kunci yang dilampirkan ke komponen di SBOM. Mereka berbeda dari kualifikasi PURL:

• qualifiers— Kualifikasi PURL. Ini menjadi bagian dari string URL paket (misalnya,pkg:deb/debian/curl@7.88.1?arch=amd64). Beberapa kualifikasi PURL membawa makna semantik ke Amazon Inspector dan memengaruhi identifikasi kerentanan. Lihat Apa itu URL paket? untuk konvensi per tipe Inspektur.

• properties- Properti komponen CycloneDX. Ini muncul dalam components[].properties array SBOM dan tidak mengubah cara komponen diidentifikasi.

Ruang nama yang dipesan

amazon:inspector:*Keluarga ruang nama properti CycloneDX disediakan untuk Amazon Inspector:

• amazon:inspector:sbom_generator:*— digunakan oleh sbomgen dan pemindai bawaannya.

• amazon:inspector:sbom_scanner:*— digunakan oleh Amazon Inspector Scan API.

Properti yang ditentukan plugin tidak boleh menggunakan ruang nama ini. Menulis ke dalam namespace yang dicadangkan dapat membayangi atau bertentangan dengan nilai-nilai yang diandalkan Inspector, dan SBOM yang dihasilkan dapat ditafsirkan secara tidak benar selama identifikasi kerentanan. Lihat Menggunakan ruang nama CycloneDX dengan Amazon Inspector untuk daftar lengkap kunci yang dicadangkan.

Aturan penamaan kunci

Kunci properti yang diteruskan sbomgen.push_package() diproses sebagai berikut:

Kunci masukan	Kunci yang dihasilkan di SBOM	Direkomendasikan untuk plugin kustom?
Berisi : (mis.,acme:my_plugin:field)	Digunakan kata demi kata	Ya - tempatkan setiap properti yang ditentukan plugin di namespace Anda sendiri
Tidak : (mis.,field)	Awalan otomatis ke amazon:inspector:sbom_generator:field	Tidak - ini menulis ke namespace yang dicadangkan

Selalu sertakan setidaknya satu titik dua dalam kunci properti yang Anda tentukan. Gunakan namespace yang unik untuk organisasi atau plugin Anda (misalnyaacme: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",
}

Properti ditetapkan oleh sbomgen

Sbomgen dapat melampirkan propertinya sendiri ke setiap komponen yang dipancarkannya. Nilai-nilai ini berasal dari amazon:inspector:sbom_generator:* namespace yang dicadangkan dan tidak boleh diproduksi oleh plugin. Perilaku runtime yang diamati:

• source_pathselalu ditambahkan oleh sbomgen.

• source_file_scannerdan source_package_collector ditambahkan saat --enable-debug-props diaktifkan.

Taksonomi lengkap kunci cadangan dipertahankan dalam panduan pengguna Amazon Inspector: Menggunakan ruang nama CycloneDX dengan Amazon Inspector.

Konstanta Properti

Konstanta kunci properti bawaan tersedia melaluisbomgen.properties. Setiap konstanta di bawah ini menyelesaikan kunci di dalam namespace yang dicadangkanamazon:inspector:sbom_generator:*. Konstanta ini ada sehingga pemindai bawaan sbomgen memancarkan kunci properti yang konsisten. Mereka bukan titik ekstensi untuk plugin khusus - menggunakannya dalam plugin khusus menulis ke namespace yang dicadangkan, yang dapat membayangi nilai yang diandalkan Inspector. Lihat Ruang nama yang dipesan di atas.

Penulis plugin khusus harus mendefinisikan properti di bawah namespace mereka sendiri (misalnyaacme:my_plugin:*) daripada menggunakan kembali konstanta ini.

Konstan	Nilai Terselesaikan
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

Grup Pemindai

Plugin Discovery harus mendeklarasikan grup pemindai mereka melalui. get_scanner_groups() Grup mengkategorikan pemindai dan memungkinkan pengguna untuk mengaktifkan atau menonaktifkan kategori secara selektif. Konstanta tersedia melaluisbomgen.groups:

Konstan	Nilai	Deskripsi
sbomgen.groups.OS	"os"	Manajer paket OS (dpkg, rpm, dll.)
sbomgen.groups.PROGRAMMING_LANGUAGE	"programming-language-packages"	Manajer paket bahasa (pip, npm, maven, dll.)
sbomgen.groups.BINARY	"binary"	Analisis biner yang dikompilasi (Go, Rust)
sbomgen.groups.PACKAGE_COLLECTOR	"pkg-scanner"	Koleksi paket umum
sbomgen.groups.EXTRA_ECOSYSTEMS	"extra-ecosystems"	Ekosistem tambahan (curl, nginx, dll.)
sbomgen.groups.CERTIFICATE	"certificate"	Pemindaian sertifikat
sbomgen.groups.CUSTOM	"custom"	Secara otomatis ditambahkan ke semua plugin kustom dimuat melalui --plugin-dir
sbomgen.groups.MACHINE_LEARNING	"machine-learning"	Deteksi model pembelajaran mesin

Contoh:

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

Konstanta Jenis Komponen

component_typeBidang di push_package() harus menjadi salah satu jenis komponen CycloneDX 1.5. Konstanta tersedia melaluisbomgen.component_types:

Konstan	Nilai
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"

Contoh:

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

Konstanta Platform

Konstanta untuk membandingkan terhadapsbomgen.get_platform(). Tersedia melaluisbomgen.platform:

Konstan	Nilai
sbomgen.platform.LINUX	"linux"
sbomgen.platform.WINDOWS	"windows"
sbomgen.platform.DARWIN	"darwin"

Contoh:

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

Info Artifak

sbomgen.get_platform()

Mengembalikan string platform runtime (misalnya,, "linux""windows","darwin").

sbomgen.get_artifact_type()

Mengembalikan jenis artefak yang dipindai (misalnya,"directory","archive").

sbomgen.should_collect_licenses()

Mengembalikan true jika pengguna mengaktifkan koleksi lisensi melalui--collect-licenses.

sbomgen.get_env_vars()

Mengembalikan variabel lingkungan dari artefak sebagai tabel {key, value} entri.

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()

Mengembalikan huruf drive sistem (misalnya,"C:") dari lingkungan artefak. Membaca variabel SystemDrive lingkungan, defaultnya "C:" jika tidak disetel. Ini setara dengan Lua. strutils.GetSystemDriverLetter()

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

Info Sistem

Fungsi-fungsi ini mengembalikan metadata tentang sistem operasi dan perangkat keras artefak. Nilai mungkin string kosong jika informasi tidak tersedia (misalnya, ketika memindai direktori tanpa metadata OS).

Fungsi	Pengembalian
sbomgen.get_os_name()	Nama OS (misalnya,"Ubuntu","Alpine Linux")
sbomgen.get_os_version()	Versi OS (misalnya,"22.04","3.18")
sbomgen.get_os_codename()	Nama kode OS (misalnya,,"jammy") "bookworm"
sbomgen.get_os_id()	Pengidentifikasi OS (misalnya,"ubuntu","alpine")
sbomgen.get_kernel_name()	Nama kernel (mis.,"Linux")
sbomgen.get_kernel_version()	String versi kernel
sbomgen.get_cpu_arch()	Arsitektur CPU (misalnya,"x86_64","aarch64")
sbomgen.get_hostname()	Nama host dari sistem

Ekspresi Reguler

Pola bawaan Lua tidak memiliki fitur seperti alternation (|), quantifier range ({n,}), dan lookahead. Untuk menutup celah ini, sbomgen mengekspos paket Go secara langsung. regexp Fungsi-fungsi ini menggunakan sintaks Go regex (RE2), bukan pola Lua.

sbomgen.regex_find(str, pattern)

Mengembalikan kecocokan pertama dari pola Go regex, atau nil jika tidak cocok.

• Pengembalian: string|nil, err

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

sbomgen.regex_match(str, pattern)

Mengembalikan grup tangkapan dari pertandingan pertama. Indeks 1 adalah pertandingan penuh, 2+ adalah grup tangkapan.

• Pengembalian: {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])

Mengembalikan semua pertandingan yang tidak tumpang tindih. Lulus n untuk membatasi hasil (default: semua).

• Pengembalian: {string, ...}|nil, err

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

sbomgen.regex_replace(str, pattern, replacement)

Menggantikan semua pertandingan. String pengganti dapat digunakan$1,$2, dll. untuk menangkap referensi grup.

• Pengembalian: string, err

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

Kapan menggunakan pola regex vs Lua

Gunakan built-in Luastring.match/string.finduntuk pola sederhana — mereka lebih cepat dan tidak memerlukan melarikan diri dari garis miring terbalik. Gunakan sbomgen.regex_* saat Anda membutuhkan:

• Pergantian: (foo|bar)

• Rentang kuantifier: \d{8,}

• Kelas karakter kompleks tidak dapat diekspresikan dalam pola Lua

Penguraian Terstruktur

Sbomgen mengekspos pembantu ringan untuk mendekode format teks terstruktur langsung ke tabel Lua.

sbomgen.json_decode(str)

Mem-parsing string JSON ke dalam tabel Lua.

• Pengembalian: 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)

Mem-parsing string XHTML ke dalam tabel Lua.

• Pengembalian: table|nil, err

Nilai XHTML menggunakan bentuk berikut:

• _name— nama elemen

• _attr— tabel atribut, saat hadir

• _text— konten teks yang dipangkas, saat hadir

• indeks numerik 1..n — elemen anak

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)

Registri Windows

Fungsi-fungsi ini menyediakan akses read-only ke registri Windows. Pada artefak non-Windows, registry_open_key mengembalikan kesalahan. Pengakses registri diinisialisasi dengan malas pada penggunaan pertama dan mendukung akses API Windows langsung (pemindaian localhost di Windows) dan penguraian sarang REGF berbasis file (pemindaian kontainer/volume).

sbomgen.registry_open_key(path)

Membuka kunci registri. Mengembalikan pegangan kunci yang harus ditutup denganregistry_close.

• Pengembalian: 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)

Membaca nilai string dari kunci registri terbuka.

• Pengembalian: string, err

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

sbomgen.registry_get_integer(key, value_name)

Membaca nilai integer dari kunci registri terbuka.

• Pengembalian: number, err

sbomgen.registry_get_strings(key, value_name)

Membaca nilai multi-string (REG_MULTI_SZ) dari kunci registri terbuka. Mengembalikan tabel string.

• Pengembalian: {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)

Mengembalikan semua nama subkunci di bawah kunci registri terbuka.

• Pengembalian: {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)

Menutup pegangan kunci registri. Pegangan kunci juga ditutup secara otomatis oleh pengumpul sampah, tetapi penutupan eksplisit disarankan.

Pencatatan log

Pesan log ditulis ke output konsol sbomgen. Setiap pesan yang dipancarkan oleh plugin secara otomatis diawali dengan label sumber dan ekosistem plugin, misalnya:

[custom:python-pip] Parsing requirements.txt

log_info,log_warn, dan log_error selalu mencetak. log_debughanya mencetak saat sbomgen dipanggil dengan. --verbose

Fungsi	Tingkat	Terlihat secara default?
sbomgen.log_debug(message)	DEBUG	Tidak - membutuhkan --verbose
sbomgen.log_info(message)	INFO	Ya
sbomgen.log_warn(message)	WARN	Ya
sbomgen.log_error(message)	ERROR	Ya

Gunakan string.format untuk pesan yang diformat:

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

Fungsi Debugging

sbomgen.breakpoint(message)

Mencetak message ke stderr dan memblokir eksekusi sampai pengguna menekan Enter. Jika message dihilangkan, mencetak pesan default.

Gunakan ini sebagai debugger kasar dengan menempatkan breakpoint pada titik-titik kunci di plugin Anda dan menjalankannya --verbose untuk melihat output log di sekitarnya.

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

Pengujian API

Fungsi di bawah testing tabel global hanya tersedia di dalam file uji plugin (*_test.lua), dimuat olehinspector-sbomgen plugin test. Mereka tidak tersedia saat runtime di plugin penemuan atau koleksi. sbomgen.*API lengkap juga tersedia di dalam file pengujian, tetapi sbomgen.* fungsi yang memerlukan artefak (misalnyasbomgen.read_file()) hanya menghasilkan hasil yang berarti ketika dipanggil dari dalam pemindaian. Untuk panduan naratif, lihat. Panduan pengujian plugin

Fungsi pemindaian

Setiap fungsi pemindaian membuat artefak dari jenis yang diberikan, menjalankan pipeline penemuan→koleksi plugin saat ini terhadapnya, dan mengembalikan temuan yang dihasilkan. pathArgumen diselesaikan relatif terhadap direktori file uji.

Fungsi	Jenis Artifak
testing.scan_directory(path)	Direktori
testing.scan_archive(path)	Direktori (alias dari) scan_directory
testing.scan_localhost(path)	Localhost
testing.scan_binary(path)	Biner
testing.scan_volume(path)	Volume
testing.scan_container(path)	Kontainer

Semua enam mengembalikan tabel hasil dengan bentuk di bawah ini.

Bentuk hasil

Setiap tabel pencarian hanya memproyeksikan bidang yang tercantum di bawah ini. Secara khusus, namespace dan tidak purl_type diproyeksikan secara terpisah - mereka dimasukkan ke dalam purl string penuh.

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)

Pernyataan

Fungsi	Tanda tangan	Deskripsi
testing.assert_equals	(expected: any, actual: any, message?: string)	Gagal jikatostring(expected) ~= tostring(actual).
testing.assert_not_equals	(expected: any, actual: any, message?: string)	Gagal jikatostring(expected) == tostring(actual).
testing.assert_true	(value: any, message?: string)	Gagal jika value ada false ataunil.
testing.assert_false	(value: any, message?: string)	Gagal value jika tidak false dan tidaknil.
testing.assert_nil	(value: any, message?: string)	Gagal value jika tidaknil.
testing.assert_not_nil	(value: any, message?: string)	Gagal jika value adanil.
testing.assert_contains	(haystack: string, needle: string, message?: string)	Gagal jika haystack tidak mengandung needle (substring match).
testing.assert_matches	(str: string, pattern: string, message?: string)	Gagal jika str tidak cocok dengan regex Go (RE2) yang diberikan.
testing.assert_length	(tbl: table, expected: integer, message?: string)	Gagal jika #tbl tidak samaexpected.

Kontrol aliran

Fungsi	Tanda tangan	Deskripsi
testing.fail	(message: string)	Gagal tes saat ini segera dengan pesan yang diberikan.
testing.skip	(message: string)	Melewatkan tes saat ini. Hasilnya dilaporkan sebagai dilewati, tidak gagal.

Uji penemuan

Setiap fungsi Lua global yang namanya dimulai dengan test_ pencocokan file *_test.lua diperlakukan sebagai tes. File tes harus duduk di sebelah a init.lua pada {phase}/{platform}/{category}/{ecosystem}/ kedalaman normal. Data perlengkapan masuk di _testdata/ sebelah file pengujian - pelari tidak turun _testdata/ saat mencari file pengujian.

Penanganan Kesalahan

Fungsi API yang gagal mengembalikan dua nilai:value, err. Pada kesuksesan, err adalahnil. Pada kegagalan, nilai pertama adalah nil dan err merupakan string kesalahan.

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

Jika sebuah plugin memunculkan kesalahan Lua yang tidak tertangani, sbomgen mencatat peringatan dan melanjutkan dengan file atau plugin berikutnya. Plugin lain tidak terpengaruh.