Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Referensi API Plugin

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

Gambaran umum

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 pustaka standar berikut secara eksplisit tidak diizinkan untuk keamanan dan stabilitas:

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

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

Plugin koleksi

Berkas I/O

Semua operasi file harus melalui sbomgen.* API. Akses sistem file langsung melalui io perpustakaan 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.

Batas akses file

Fungsi sbomgen.* file membatasi pembacaan ke artefak di bawah inventaris. Jalur yang menyelesaikan di luar root artefak — misalnya melalui ../ traversal — ditolak, dan panggilan mengembalikan kesalahan daripada membaca sistem file host. Ini berlaku untukread_file,open_file,read_dir,file_stat, dan binary/hash para pembantu yang mengambil jalan.

Pengecualiannya adalah tipe localhost artefak, yang menginventarisasi host itu sendiri; di sana sistem file host adalah artefak, jadi pembacaan tidak terbatas pada root yang lebih sempit.

Batas ini mengatur pembacaan file saja. Itu tidak membatasi apa yang ditulis plugin ke dalam SBOM — lihat. Isi SBOM tidak disanitasi

sbomgen.get_file_list ()

Mengembalikan semua jalur file dalam artefak sebagai tabel string.

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

Membaca seluruh isi file dan mengembalikannya sebagai string.

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

sbomgen.open_file (jalur)

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

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

Mengembalikan file yang cocok dengan pola Go filepath.Match glob. Pola dicocokkan dengan nama file dasar. Symlink dilewati; hanya file konkret yang dikembalikan.

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

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.

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

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.

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

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

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

Mengembalikan file yang jalurnya dinormalisasi garis miring ke depan cocok dengan pola regex Go (RE2) yang diberikan. Pencocokan terjadi di luar Lua VM, yang membuat ini efisien pada daftar file besar.

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

Kinerja: find_files_by_* vs get_file_list

Untuk plugin penemuan, pilihfind_files_by_name,find_files_by_suffix, atau find_files_by_path_regex ulangi 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 (jalur)

Daftar entri dalam direktori.

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

Mengembalikan metadata tentang file.

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 (jalur, entry_path)

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

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

sbomgen.search_binary (jalur, regex)

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

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

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

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

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 (jalur, 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.

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.

fh:baca (n)

Membaca hingga n byte. Kembali nil di EOF.

fh:tutup ()

Menutup pegangan file. Selalu tutup pegangan saat selesai.

Utilitas Biner

sbomgen.hash (data, algoritma)

Mengembalikan intisari hex-encode dari string byte dalam memori di bawah algoritma yang diberikan. Pasangkan dengan sbomgen.read_file(path) untuk melakukan hash file yang sudah Anda baca untuk diuraikan - lebih disukai daripada sbomgen.hash_file(path) saat Anda membutuhkan byte dan intisari, karena hash tidak membaca ulang file tersebut.

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 (jalur, algoritma)

Mengembalikan intisari hex-encode dari isi file di bawah algoritma yang diberikan. Merutekan pembacaan melalui I/O lapisan artefak, sehingga bekerja secara seragam di seluruh artefak direktori, kontainer, arsip, volume, dan localhost. Gunakan ini ketika intisari adalah satu-satunya hal yang Anda butuhkan dari file.

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

Setara dengansbomgen.hash_file(path, "SHA-256").

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

sbomgen.contains_bytes (jalur, pola)

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

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

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.

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

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

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

sbomgen.parse_file_version (jalur)

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

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:

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

Hash Komponen

hashesBidang opsional pada intisari integritas sbomgen.push_package() rekaman untuk komponen. Entri dikunci berdasarkan nama algoritme dan diserialisasikan ke dalam components[].hashes array CycloneDX, cocok dengan skema yang diharapkan Amazon Inspector.

Algoritme yang didukung

Gunakan konstanta di bawah sbomgen.hash_algorithms sehingga nama algoritma diteruskan kesbomgen.hash()/sbomgen.hash_file()adalah string yang sama yang diterima olehpush_package({ hashes = ... }):

Aturan validasi

push_package()memvalidasi hashes sebelum memancarkan temuan. Paket yang validasi hash-nya gagal dijatuhkan dan peringatan dicatat. Validasi:

Contoh: hashing manifes dan melampirkan intisari

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

Ketika intisari adalah satu-satunya hal yang Anda butuhkan dari file, sbomgen.hash_file(path, algo) lebih suka membaca file dua kali — itu merutekan pembacaan melalui I/O lapisan artefak dalam satu lintasan.

Properti CycloneDX

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

Ruang nama yang dipesan

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

Plugin-defined properti 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:

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:

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

Isi SBOM tidak disanitasi

Sbomgentidak memeriksa atau memfilter data yang dipancarkan plugin. Nama komponen, versi, PURL, hash, dan nilai properti ditulis ke SBOM sebagaimana disediakan. Sbomgentidak mendeteksi atau menyunting rahasia, kredensyal, token, atau data sensitif lainnya - jika plugin menempatkan nilai seperti itu ke dalam temuan, itu muncul di output SBOM dan bergerak ke mana pun SBOM diterbitkan.

Anda bertanggung jawab atas apa yang ditulis plugin Anda. Hanya memancarkan data yang berasal dari artefak yang ingin Anda inventarisasi, dan perlakukan SBOM sebagai artefak yang dapat dibagikan saat memutuskan apa yang akan disertakan.

Konstanta Properti

Built-in konstanta kunci properti 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.

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:

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:

Contoh:

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

Konstanta Algoritma Hash

Konstanta untuk parameter algoritmasbomgen.hash(),sbomgen.hash_file(), dan hashes bidang. sbomgen.push_package() Nilai string cocok dengan nama algoritma hash CycloneDX sehingga konstanta yang sama mengalir melalui seluruh jalur hashing tanpa terjemahan.

Contoh:

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

Konstanta Platform

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

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, default ke "C:" jika tidak disetel. Ini setara dengan Lua. strutils.GetSystemDriverLetter()

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

sbomgen.resolve_glob_paths (pola)

Memperluas pola glob sistem file terhadap sistem file host. Localhost-only: mengembalikan nil ditambah kesalahan pada jenis artefak lainnya.

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

Perilaku:

Cross-platform pemisah jalur:

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

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

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

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

sbomgen.regex_match (str, pola)

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

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, pola [, n])

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

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

sbomgen.regex_replace (str, pola, penggantian)

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

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:

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.

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.

Nilai XHTML menggunakan bentuk berikut:

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). container/volume

sbomgen.registry_open_key (jalur)

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

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 (kunci, value_name)

Membaca nilai string dari kunci registri terbuka.

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

sbomgen.registry_get_integer (kunci, value_name)

Membaca nilai integer dari kunci registri terbuka.

sbomgen.registry_get_strings (kunci, value_name)

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

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

Mengembalikan semua nama subkunci di bawah kunci registri terbuka.

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

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

Gunakan string.format untuk pesan yang diformat:

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

Fungsi Debugging

sbomgen.breakpoint (pesan)

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.

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

Mengontrol aliran

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.