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

## Gambaran umum
<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.) Dan membatasi pembacaan ke artefak di bawah inventaris (lihat). [Batas akses file](#sbomgen-plugin-api-reference-file-access-boundary) | 
| os | System-level operasi (os.execute,os.remove,os.rename,os.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` perpustakaan 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. 

### Batas akses file
<a name="sbomgen-plugin-api-reference-file-access-boundary"></a>

 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 untuk`read_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-plugin-api-reference-sbom-contents-not-sanitized) 

### `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 300 artefak. K-file Gunakan `get_file_list()` hanya ketika logika pencocokan Anda tidak dapat diekspresikan dengan salah satu di atas.  
The `find_files_by_*` and `glob_find_files` helper melewatkan symlink, hanya mengembalikan file konkret, jadi alias symlink dan targetnya tidak keduanya diinventarisasi. `get_file_list()`mengembalikan setiap entri, termasuk symlink.

```
-- 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)`
<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 (jalur)`
<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 (pola)`
<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. Symlink dilewati; hanya file konkret yang dikembalikan. 
+ **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 (nama)`
<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 termasuk symlink (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 (nama)`
<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 termasuk symlink (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 (sufiks)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-suffix-suffixes"></a>

 Mengembalikan file yang path penuh (forward-slash-normalized) 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 termasuk symlink (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 (pola)`
<a name="sbomgen-plugin-api-reference-sbomgen-find-files-by-path-regex-patterns"></a>

 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. 
+ **Parameter:** `patterns` — tabel string Go regex
+ **Pengembalian:** `{string, ...}` - jalur file yang cocok, tidak termasuk symlink (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` 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)`
<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 (jalur)`
<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 (jalur, 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 (jalur, regex)`
<a name="sbomgen-plugin-api-reference-sbomgen-search-binary-path-regex"></a>

 Mem-parsing file sebagai ELF, PE, atau Mach-O biner 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 (jalur, regex [, n])`
<a name="sbomgen-plugin-api-reference-sbomgen-search-binary-all-path-regex-n"></a>

 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. 
+ **Pengembalian:** `{string, ...}|nil, err` — tabel string yang cocok, atau nihil jika tidak ada yang cocok

```
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)`
<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:baca (n)`
<a name="sbomgen-plugin-api-reference-fh-read-n"></a>

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

### `fh:tutup ()`
<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.hash (data, algoritma)`
<a name="sbomgen-plugin-api-reference-sbomgen-hash-data-algorithm"></a>

 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. 
+ **Pengembalian:** `string, err`
+ **Algoritma:** lihat [Hash Komponen](#sbomgen-plugin-api-reference-component-hashes) daftar konstanta algoritma yang diterima.

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

 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. 
+ **Pengembalian:** `string, err`

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

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

**penting**  
 **Usang.** Gunakan `sbomgen.hash_file(path, sbomgen.hash_algorithms.SHA256)` sebagai gantinya. Alias ini dipertahankan untuk kompatibilitas mundur dan akan terus bekerja, tetapi akan dihapus di rilis mendatang. Plugin baru harus memanggil `hash_file` sehingga pilihan algoritme eksplisit. 

 Setara dengan`sbomgen.hash_file(path, "SHA-256")`. 
+ **Pengembalian:** `string, err`

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

### `sbomgen.contains_bytes (jalur, pola)`
<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 (jalur)`
<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 (jalur)`
<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 (jalur)`
<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) | 
| hashes | tabel | Tidak | Hash komponen yang dikunci dengan nama algoritma; lihat [Hash Komponen](#sbomgen-plugin-api-reference-component-hashes) | 
| 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",
    },
    hashes = {
        [sbomgen.hash_algorithms.SHA256] = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
    },
})
```

## Hash Komponen
<a name="sbomgen-plugin-api-reference-component-hashes"></a>

 `hashes`Bidang 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
<a name="sbomgen-plugin-api-reference-component-hashes-supported-algorithms"></a>

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


| **Konstan** | **Nilai** | **Panjang intisari hex** | 
| --- | --- | --- | 
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" | 40 | 
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" | 64 | 

### Aturan validasi
<a name="sbomgen-plugin-api-reference-component-hashes-validation-rules"></a>

 `push_package()`memvalidasi `hashes` sebelum memancarkan temuan. Paket yang validasi hash-nya gagal dijatuhkan dan peringatan dicatat. Validasi: 
+ Nama algoritma harus cocok dengan entri di `sbomgen.hash_algorithms` (peka huruf besar/kecil, tepat `"SHA-1"` atau`"SHA-256"`).
+ Nilai harus non-kosong, digit heksadesimal huruf kecil.
+ Nilai harus panjang yang benar untuk algoritme (40 karakter untuk SHA-1, 64 karakter untuk SHA-256).
+ Validasi bersifat rekursif: hash cacat di dalam `children[].hashes` menolak seluruh paket.

### Contoh: hashing manifes dan melampirkan intisari
<a name="sbomgen-plugin-api-reference-component-hashes-example"></a>

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

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

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

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

 **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](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) | Auto-prefixed untuk 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. 

### Isi SBOM tidak disanitasi
<a name="sbomgen-plugin-api-reference-sbom-contents-not-sanitized"></a>

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

 Built-in konstanta kunci properti 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 Algoritma Hash
<a name="sbomgen-plugin-api-reference-hash-algorithm-constants"></a>

 Konstanta untuk parameter algoritma`sbomgen.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. 


| **Konstan** | **Nilai** | 
| --- | --- | 
| sbomgen.hash\_algorithms.SHA1 | "SHA-1" | 
| sbomgen.hash\_algorithms.SHA256 | "SHA-256" | 

 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
<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, 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)`
<a name="sbomgen-plugin-api-reference-sbomgen-resolve-glob-paths"></a>

 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:** 
+ Sintaks pola mengikuti Go [https://pkg.go.dev/path/filepath#Match](https://pkg.go.dev/path/filepath#Match):`*`,, `?``[abc]`,`[a-z]`.
+ Pola input dan jalur output dinormalisasi: pemisah redundan (), segmen titik (`a//b`), dan pemisah trailing (`a/./b`) diciutkan. `a/b/`
+ Output dideduplikasi; kejadian pertama dari jalur menang. Urutan pola input dipertahankan di seluruh hasil.
+ Pola yang tidak cocok tidak mengembalikan entri. Empty-string pola diam-diam dilewati. Pola cacat (misalnya tanda kurung yang tidak cocok) memancarkan peringatan dan dilewati.

 **Cross-platform pemisah jalur:** 
+ **Gunakan garis miring maju (`/`) untuk semua jalur.** Garis miring maju berfungsi di Linux, macOS, dan Windows; Logika jalur file Go menerjemahkannya ke pemisah asli di Windows.
+ **Pemisah garis miring terbalik hanya berfungsi di Windows.** Di Linux dan macOS, `\` adalah karakter nama file literal, bukan pemisah jalur — pola seperti tidak `"C:\\Users\\*"` cocok dengan sistem POSIX.
+ **Hindari Windows-style jalur literal dalam string Lua.** String Lua seperti `"C:\Users"` ditafsirkan sebagai `C:<form-feed>sers` karena `\U` bukan pelarian Lua yang valid (dan`\f`,, `\t` dll. adalah)`\n`, sehingga polanya gagal secara diam-diam. Gunakan garis miring maju, garis miring terbalik yang lolos (`"C:\\Users"`), atau string mentah braket panjang (). `[[C:\Users]]`

## 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, pola)`
<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, pola)`
<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, pola [, 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, pola, penggantian)`
<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). container/volume 

### `sbomgen.registry_open_key (jalur)`
<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 (kunci, 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 (kunci, 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 (kunci, 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 (kunci)`
<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 (kunci)`
<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 (pesan)`
<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. | 

### Mengontrol 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.