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

# Referensi API Plugin
<a name="sbomgen-plugin-api-reference"></a>

 Referensi API lengkap untuk plugin Lua inspector-sbomgen. Untuk panduan menulis plugin, lihat[Panduan pengembang plugin](sbomgen-plugin-developer-guide.md). Untuk pengujian, lihat[Panduan pengujian plugin](sbomgen-plugin-testing-guide.md). 

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

 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_name``subscribe_to_event`, dan sebagainya) yang dipanggil sbomgen pada titik yang ditentukan dalam siklus hidup plugin. Ini didokumentasikan dalam[Plugin Siklus Hidup Global](#sbomgen-plugin-api-reference-plugin-lifecycle-globals). 

 Di dalam `*_test.lua` file, sbomgen juga mengekspos `testing` global yang memungkinkan penulis pengujian mendorong pipeline penemuan→pengumpulan dan membuat pernyataan. Lihat [Pengujian API](#sbomgen-plugin-api-reference-testing-api). 

### Pembatasan Kotak Pasir
<a name="sbomgen-plugin-api-reference-sandbox-restrictions"></a>

 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. `sbomgen`API memastikan plugin berinteraksi dengan lapisan abstraksi artefak, yang memberikan perilaku yang konsisten baik memindai direktori, gambar kontainer, arsip, atau volume.

## Plugin Siklus Hidup Global
<a name="sbomgen-plugin-api-reference-plugin-lifecycle-globals"></a>

 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
<a name="sbomgen-plugin-api-reference-discovery-plugins"></a>


| **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
<a name="sbomgen-plugin-api-reference-collection-plugins"></a>


| **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
<a name="sbomgen-plugin-api-reference-file-i-o"></a>

 Semua operasi file harus melalui `sbomgen.*` API. Akses sistem file langsung melalui `io` pustaka Lua tidak tersedia (lihat). [Pembatasan Kotak Pasir](#sbomgen-plugin-api-reference-sandbox-restrictions) 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()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-file-list"></a>

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

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

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-glob-find-files-pattern"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-name-names"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-name-icase-names"></a>

 Mengembalikan file yang nama dasarnya cocok dengan salah satu nama yang diberikan, mengabaikan kasus. Misalnya, `"version"` korek api`VERSION`,`Version`, dan`version`. Seperti`find_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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-suffix-suffixes"></a>

 Mengembalikan file yang full (forward-slash-normalized) path berakhir dengan salah satu sufiks yang diberikan. Seperti`find_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)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-path-regex-patterns"></a>

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

 Untuk plugin penemuan, pilih, `find_files_by_name``find_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)`
<a name="sbomgen-plugin-api-reference-sbomgen-read-dir-path"></a>

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

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-read-zip-entry-path-entry-path"></a>

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

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

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

 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
<a name="sbomgen-plugin-api-reference-filehandle-methods"></a>

 FileHandle objek dikembalikan oleh`sbomgen.open_file()`. 

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

 Membaca baris berikutnya (tanpa karakter baris baru). Kembali `nil` di EOF. 
+ **Pengembalian:** `string|nil, err`

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

 Membaca hingga `n` byte. Kembali `nil` di EOF. 
+ **Pengembalian:** `string|nil, err`

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

 Menutup pegangan file. Selalu tutup pegangan saat selesai. 

## Utilitas Biner
<a name="sbomgen-plugin-api-reference-binary-utilities"></a>

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

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

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

 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_version`Bidang `product_version` dan berasal dari `FixedFileInfo` struktur PE, diformat sebagai`"major.minor.build.revision"`. `string_table`Bidang 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`,, `ProductName``FileDescription`, 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-parse-product-version-path"></a>

 Pembungkus kenyamanan yang mengembalikan hanya string versi produk dari biner PE. FixedFileInfo Setara dengan menelepon `get_pe_version_info(path)` dan membaca`product_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)`
<a name="sbomgen-plugin-api-reference-sbomgen-parse-file-version-path"></a>

 Pembungkus kenyamanan yang mengembalikan hanya string versi file dari biner PE. FixedFileInfo Setara dengan menelepon `get_pe_version_info(path)` dan membaca`file_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
<a name="sbomgen-plugin-api-reference-package-output"></a>

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

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

 `pkg`Tabel 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](#sbomgen-plugin-api-reference-cyclonedx-properties) | 
| 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
<a name="sbomgen-plugin-api-reference-cyclonedx-properties"></a>

 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?](https://docs.aws.amazon.com/inspector/latest/user/sbom-generator-purl-sbom.html) 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
<a name="sbomgen-plugin-api-reference-reserved-namespaces"></a>

 `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](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) kunci yang dicadangkan. 

### Aturan penamaan kunci
<a name="sbomgen-plugin-api-reference-key-naming-rules"></a>

 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 (misalnya`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",
}
```

### Properti ditetapkan oleh sbomgen
<a name="sbomgen-plugin-api-reference-properties-set-by-sbomgen"></a>

 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_path`selalu ditambahkan oleh sbomgen.
+ `source_file_scanner`dan `source_package_collector` ditambahkan saat `--enable-debug-props` diaktifkan.

 Taksonomi lengkap kunci cadangan dipertahankan dalam panduan pengguna Amazon Inspector[: Menggunakan ruang nama CycloneDX](https://docs.aws.amazon.com/inspector/latest/user/cyclonedx-namespace.html) dengan Amazon Inspector. 

## Konstanta Properti
<a name="sbomgen-plugin-api-reference-property-constants"></a>

 Konstanta kunci properti bawaan tersedia melalui`sbomgen.properties`. Setiap konstanta di bawah ini menyelesaikan kunci di dalam namespace yang dicadangkan`amazon: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](#sbomgen-plugin-api-reference-reserved-namespaces) di atas. 

 Penulis plugin khusus harus mendefinisikan properti di bawah namespace mereka sendiri (misalnya`acme: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
<a name="sbomgen-plugin-api-reference-scanner-groups"></a>

 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 melalui`sbomgen.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
<a name="sbomgen-plugin-api-reference-component-type-constants"></a>

 `component_type`Bidang di `push_package()` harus menjadi salah satu jenis komponen CycloneDX 1.5. Konstanta tersedia melalui`sbomgen.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
<a name="sbomgen-plugin-api-reference-platform-constants"></a>

 Konstanta untuk membandingkan terhadap`sbomgen.get_platform()`. Tersedia melalui`sbomgen.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
<a name="sbomgen-plugin-api-reference-artifact-info"></a>

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

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

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

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

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

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

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

 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()`
<a name="sbomgen-plugin-api-reference-sbomgen-get-system-drive"></a>

 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
<a name="sbomgen-plugin-api-reference-system-info"></a>

 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
<a name="sbomgen-plugin-api-reference-regular-expressions"></a>

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

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

 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])`
<a name="sbomgen-plugin-api-reference-sbomgen-regex-find-all-str-pattern-n"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-regex-replace-str-pattern-replacement"></a>

 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
<a name="sbomgen-plugin-api-reference-when-to-use-regex-vs-lua-patterns"></a>

 Gunakan built-in Lua`string.match`/`string.find`untuk 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
<a name="sbomgen-plugin-api-reference-structured-parsing"></a>

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

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

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

 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
<a name="sbomgen-plugin-api-reference-windows-registry"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-open-key-path"></a>

 Membuka kunci registri. Mengembalikan pegangan kunci yang harus ditutup dengan`registry_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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-string-key-value-name"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-integer-key-value-name"></a>

 Membaca nilai integer dari kunci registri terbuka. 
+ **Pengembalian:** `number, err`

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

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-get-subkeys-key"></a>

 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-registry-close-key"></a>

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

## Pencatatan log
<a name="sbomgen-plugin-api-reference-logging"></a>

 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_debug`hanya 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
<a name="sbomgen-plugin-api-reference-debugging-functions"></a>

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

 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
<a name="sbomgen-plugin-api-reference-testing-api"></a>

 Fungsi di bawah `testing` tabel global hanya tersedia di dalam file uji plugin (`*_test.lua`), dimuat oleh`inspector-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 (misalnya`sbomgen.read_file()`) hanya menghasilkan hasil yang berarti ketika dipanggil dari dalam pemindaian. Untuk panduan naratif, lihat. [Panduan pengujian plugin](sbomgen-plugin-testing-guide.md) 

### Fungsi pemindaian
<a name="sbomgen-plugin-api-reference-scan-functions"></a>

 Setiap fungsi pemindaian membuat artefak dari jenis yang diberikan, menjalankan pipeline penemuan→koleksi plugin saat ini terhadapnya, dan mengembalikan temuan yang dihasilkan. `path`Argumen 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
<a name="sbomgen-plugin-api-reference-result-shape"></a>

 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
<a name="sbomgen-plugin-api-reference-assertions"></a>


| **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
<a name="sbomgen-plugin-api-reference-control-flow"></a>


| **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
<a name="sbomgen-plugin-api-reference-test-discovery"></a>

 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
<a name="sbomgen-plugin-api-reference-error-handling"></a>

 Fungsi API yang gagal mengembalikan dua nilai:`value, err`. Pada kesuksesan, `err` adalah`nil`. 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.