Ikhtisar Mulai Cepat: Membuat Plugin Baru Pengaturan IDE Struktur Direktori Plugin Plugin Penemuan Plugin Koleksi Menjalankan Plugin Anda Daftar Pemindai yang Tersedia Pemilihan Pemindai Aturan Tabrakan Plugin Debugging Referensi API Penanganan Kesalahan Pembatasan Kotak Pasir Berbagi Kode Antar Plugin

Panduan pengembang plugin

Panduan ini menjelaskan cara memperluas Amazon Inspector SBOM Generator (inspector-sbomgen) dengan plugin Lua kustom. Plugin memungkinkan Anda menambahkan dukungan untuk ekosistem paket baru tanpa memodifikasi kode sumber sbomgen atau harus mengkompilasi ulang.

Untuk katalog fungsi lengkap, lihatReferensi API Plugin. Untuk panduan tentang tes menulis, lihatPanduan pengujian plugin.

Ikhtisar

Plugin Sbomgen ditulis dalam Lua, dan ikuti pipeline dua langkah:

Discovery — pindai daftar file artefak dan laporkan file mana yang relevan dengan ekosistem Anda.
Koleksi — mengurai setiap file yang ditemukan dan mendorong temuan paket ke dalam SBOM.

Model Acara Plugin

Plugin Discovery membutuhkan cara untuk memberi tahu plugin koleksi bahwa file yang berisi metadata paket ditemukan di artefak di bawah inventaris. Untuk memfasilitasi berbagi data ini, plugin penemuan menentukan nama acara dan mengembalikan daftar jalur file. Plugin koleksi berlangganan acara itu dan menerima setiap jalur file yang cocok. Ini memisahkan deteksi file dari penguraian - Anda dapat memiliki satu plugin penemuan memberi makan beberapa kolektor (pola penggemar). Namun, setiap plugin penemuan harus memiliki nama acara yang unik, dan setiap plugin koleksi harus memiliki nama kolektor yang unik. Lihat Aturan Tabrakan Plugin untuk detail.

Pengembang dapat mengenali ini sebagai pola desain pengamat.

Desain ini memungkinkan satu plugin penemuan memicu beberapa analisis independen dengan cara yang berkinerja baik. Misalnya, satu plugin penemuan dapat menemukan masing-masing requirements.txt dalam artefak, lalu memberi makan:

Kolektor paket yang mem-parsing setiap baris menjadi temuan SBOM ()name==version.
Kolektor rahasia yang menandai baris yang berisi kunci API atau token yang secara tidak sengaja disematkan sebagai versi.
Kolektor kebijakan yang melaporkan penentu versi unpinned atau wildcard.

Setiap kolektor berjalan secara independen terhadap daftar file yang sama tanpa berjalan kembali sistem file artefak. Ini juga memungkinkan pembuat plugin untuk menambahkan plugin koleksi baru yang berlangganan acara yang ada tanpa harus mengubah plugin penemuan yang sesuai.

Mulai Cepat: Membuat Plugin Baru

Cara tercepat untuk membuat plugin baru adalah menggunakan perintah perancah bawaan:


inspector-sbomgen plugin new

Perintah meminta nama plugin dan direktori proyek. Menekan Enter menerima default yang ditunjukkan dalam tanda kurung:


Plugin name (identifies the software ecosystem your plugin will inventory, e.g. debian-dpkg, rhel-rpm, python-pip, cmake) [my-custom-ecosystem]: cmake
Project directory [my-sbomgen-plugins]:

Anda juga dapat meneruskan argumen secara langsung:


inspector-sbomgen plugin new --name cmake --path /tmp/custom-plugins

Dimulai dengan contoh kerja

Jika Anda ingin bereksperimen dengan plugin sebelum menulis logika Anda sendiri, buat plugin baru menggunakan --with-example bendera:


inspector-sbomgen plugin new --with-example

Ini menghasilkan proyek plugin yang berfungsi penuh dengan parser lockfile sampel, data uji, dan tes lulus. Plugin contoh menemukan example.lock file, mem-parsing name==version entri, dan mendorong paket ke dalam SBOM. Anda dapat segera menjalankan pengujian untuk melihat sistem plugin beraksi, lalu memodifikasi kode untuk menargetkan ekosistem Anda yang sebenarnya.

Untuk scaffolding lanjutan yang mencakup semua fungsi penggantian opsional (get_scanner_name,,, penemuan multi-peristiwa get_event_nameget_scanner_groups, dll.), Gunakan --with-overrides flag (selengkapnya tentang ini nanti):


inspector-sbomgen plugin new --with-overrides

Menyelesaikan Plugin Anda

Setelah scaffolding, file plugin yang dihasilkan berisi TODO penanda yang menunjukkan di mana harus menambahkan logika spesifik ekosistem Anda. Kerjakan spidol ini untuk mengubah perancah menjadi plugin yang berfungsi:

Ganti semua TODO spidol dengan nilai aktual Anda
Perbarui pola file discover() agar sesuai dengan file target Anda
Terapkan logika parsing collect() dan panggil sbomgen.push_package() untuk setiap paket

Uji Plugin Anda

Ada dua cara untuk menguji plugin Anda:

1. Built-in test harness - Gunakan inspector-sbomgen plugin test untuk memvalidasi logika plugin selama pengembangan. Ini menjalankan file init_test.lua pengujian Anda tanpa memerlukan artefak nyata untuk memindai:


inspector-sbomgen plugin test --path ./my-plugins

Lihat detail tentang menulis file pengujian dan menggunakan testing.* API. Panduan pengujian plugin

2. End-to-endscan - Panggil plugin Anda menggunakan perintah sbomgen standar untuk memverifikasi itu bekerja terhadap artefak nyata. Untuk pendekatan ini, Anda perlu menyediakan artefak yang berisi file target plugin Anda (misalnya, direktori dengan requirements.txt atau setara) dan jalur ke direktori plugin Anda:


inspector-sbomgen directory \
    --path /path/to/test/dir \
    --plugin-dir ./my-plugins \
    --disable-native-scanners \
    -o sbom.json

--disable-native-scannersBendera memastikan hanya plugin Lua Anda yang berjalan, membuatnya lebih mudah untuk menguji tanpa output dari pemindai bawaan (asli).

Pengaturan IDE

Sbomgen menyediakan penyelesaian kode, pemeriksaan tipe, dan dokumentasi sebaris untuk seluruh sbomgen.* API di VS Code.

Kode VS dengan Server Bahasa Lua

Instal ekstensi Lua: sumneko.lua
Buka .lua file apa pun di proyek plugin Anda

Itu dia! plugin newPerintah menghasilkan .vscode/settings.json dan library/sbomgen.lua yang secara otomatis terdeteksi oleh Server Bahasa Lua. Anda akan segera mendapatkan:

Penyelesaian kode untuk semua sbomgen.* fungsi
Petunjuk parameter dengan tipe
Dokumentasi hover
Jenis pemeriksaan

Struktur Direktori Plugin

Plugin penemuan dan koleksi Sbomgen harus mematuhi struktur direktori berikut:


{plugin-dir}/
├── discovery/
│   └── {platform}/
│       └── {category}/
│           └── {ecosystem}/
│               └── init.lua          # REQUIRED entrypoint
└── collection/
    └── {platform}/
        └── {category}/
            └── {ecosystem}/
                └── init.lua          # REQUIRED entrypoint

Nama-nama direktori ini membawa arti semantik — sbomgen menggunakannya untuk mendapatkan metadata default untuk plugin Anda, termasuk nama pemindai, nama acara, grup pemindai, dan pemfilteran platform. Ini mengurangi jumlah pengembang boilerplate jika tidak harus menulis. Memilih nilai yang benar memastikan plugin Anda terintegrasi dengan benar dengan pemilihan pemindai dan model eksekusi sbomgen.

Bagian di bawah ini mengeksplorasi struktur direktori secara lebih rinci, memberikan panduan tentang makna dan konvensi semantik.

Platform

Direktori platform mengontrol sistem operasi mana yang dijalankan plugin Anda.

Nilai	Kapan harus digunakan
`cross-platform`	Plugin berfungsi pada OS apa pun (kebanyakan plugin)
`linux`	Logika deteksi spesifik Linux
`windows`	Logika deteksi khusus Windows
`macos`	Logika deteksi khusus macOS

Kategori

Direktori kategori menentukan grup pemindai default yang ditetapkan ke plugin Anda, yang mengontrol apakah itu berjalan secara default atau memerlukan opt-in eksplisit. Lihat Pemilihan Pemindai bagaimana grup memengaruhi eksekusi.

Nilai	Grup default	Kapan harus digunakan
`proglang`	`programming-language-packages`, `pkg-scanner`	Paket bahasa pemrograman (pip, npm, maven, dll.)
`os`	`os`, `pkg-scanner`	Manajer paket OS (dpkg, rpm, apk, dll.)
`extra-ecosystems`	`extra-ecosystems`, `pkg-scanner`	Aplikasi dan runtime (nginx, curl, wordpress, dll.)

Jika Anda menggunakan nama kategori yang tidak cocok dengan salah satu di atas, nama kategori itu sendiri digunakan sebagai grup.

Ekosistem

Nama untuk ekosistem paket tertentu (misalnya,, python-pippython-poetry,debian-dpkg,curl). Nama tanda hubung adalah konvensi umum tetapi bukan persyaratan yang ketat.

Nama pemindai dan nama kolektor berasal langsung dari nama direktori ekosistem.

Pasangan nama acara

Plugin penemuan dan koleksi di jalur direktori yang sama secara otomatis dipasangkan. Misalnya, plugin penemuan discovery/cross-platform/proglang/python-pip/ secara otomatis berpasangan dengancollection/cross-platform/proglang/python-pip/.

Anda dapat mengganti ini dengan mendefinisikan get_event_name() dan subscribe_to_event() di plugin Anda.

Plugin Penemuan

Plugin penemuan hanya membutuhkan discover() fungsinya. Semua fungsi lainnya bersifat opsional — default berasal dari jalur direktori.

Sebagian besar plugin penemuan bekerja dengan mencari file yang nama atau jalurnya mengidentifikasi ekosistem tertentu — misalnya, untuk pip requirements.txt Python, untuk npm, atau package.json untuk kargo Rust. Cargo.lock sbomgen.find_files_by_*Fungsi melakukan pencocokan ini di luar VM Lua, yang membuatnya jauh lebih cepat daripada mengulangi daftar file lengkap di Lua:


-- REQUIRED: Scans the artifact and returns a table of file paths.
function discover()
    return sbomgen.find_files_by_name({"requirements.txt"})
end

discover()harus mengembalikan tabel Lua (array) string. Jika tidak ada file yang ditemukan, kembalikan tabel kosong{}.

Pola penemuan umum

Tujuan	Fungsi yang direkomendasikan
Cocokkan satu atau lebih nama file yang tepat	`sbomgen.find_files_by_name({names})`
Cocokkan nama file kasus-tidak peka huruf besar/kecil	`sbomgen.find_files_by_name_icase({names})`
Cocokkan dengan sufiks jalur (mis.,`/pom.properties`)	`sbomgen.find_files_by_suffix({suffixes})`
Cocokkan dengan regex jalur penuh	`sbomgen.find_files_by_path_regex({patterns})`
Pencocokan nama dasar gaya glob (mis.,) `*.lock`	`sbomgen.glob_find_files(pattern)`

Ketika logika Anda memerlukan pasca-pemfilteran — misalnya, menjaga file tetap cocok dengan sufiks tetapi tidak termasuk direktori build-output — menggabungkan panggilan dengan loop Lua: find_files_by_*


function discover()
    local found = {}
    for _, f in ipairs(sbomgen.find_files_by_suffix({".conda-meta.json"})) do
        if not f:match("[/\\]%.cache[/\\]") then
            table.insert(found, f)
        end
    end
    return found
end

Hindari sbomgen.get_file_list() penemuan kecuali tidak ada pencocokan lain yang cocok — itu menyalin setiap jalur ke Lua VM dan dapat memakan waktu beberapa detik pada artefak besar. Lihat Referensi API Plugin untuk detailnya.

Penemuan multi-acara

Secara default, semua file yang dikembalikan oleh discover() dipublikasikan ke satu acara (dariget_event_name()). Jika pemindai Anda perlu merutekan file yang berbeda ke kolektor yang berbeda, kembalikan tabel yang dikunci sebagai gantinya:


function discover()
    return {
        EventNameFoundCurl = sbomgen.find_files_by_name({"curl", "curl.exe"}),
        EventNameFoundLibcurl = sbomgen.find_files_by_name({"curlver.h"}),
    }
end

Ketika discover() mengembalikan tabel dengan kunci string, setiap kunci diperlakukan sebagai nama acara terpisah dan nilainya (tabel jalur file) dipublikasikan ke acara itu. Plugin koleksi berlangganan acara tertentu melalui subscribe_to_event() seperti biasa.

Ini kompatibel ke belakang — mengembalikan tabel sekuensial {"file1", "file2"} masih berfungsi sebagai mode acara tunggal. Deteksi otomatis: tabel dengan tombol string apa pun adalah multi-acara, tabel dengan hanya kunci bilangan bulat (atau kosong) adalah peristiwa tunggal.

Bila menggunakan multi-event, tidak get_event_name() digunakan untuk penerbitan (nama acara berasal dari tombol tabel dikembalikan). Namun, itu masih dipanggil selama pemuatan plugin untuk deteksi tabrakan, jadi itu harus mengembalikan nilai unik atau dihilangkan untuk menggunakan default.

Fungsi penemuan opsional

Semua ini memiliki default waras yang berasal dari jalur direktori. Tentukan mereka hanya jika Anda perlu mengganti:

Fungsi	Default	Ganti saat...
`get_scanner_name()`	`{ecosystem}`(misalnya,`python-pip`)	Anda menginginkan nama pemindai khusus
`get_scanner_description()`	`"Lua discovery plugin: {ecosystem}"`	Anda ingin deskripsi khusus
`get_scanner_groups()`	Berasal dari direktori kategori	Anda membutuhkan grup non-standar
`get_event_name()`	Berasal dari jalur direktori	Anda memerlukan perutean acara khusus
`get_localhost_scan_paths()`	Tidak ada	Plugin Anda membutuhkan jalur tertentu yang dipindai selama `localhost` pemindaian

Jalur pemindaian localhost

Ketika sbomgen menjalankan localhost pemindaian, ia berjalan direktori yang ditentukan pengguna ditambah jalur default yang dideklarasikan oleh pemindai. Secara default, plugin penemuan Lua tidak menyumbangkan jalur apa pun, sehingga file di luar direktori yang ditentukan pengguna tidak akan muncul dalam daftar file.

Tentukan get_localhost_scan_paths() untuk mengembalikan direktori atau jalur file yang harus disertakan oleh walker localhost:


function get_localhost_scan_paths()
    return {
        "/usr/bin",
        "/usr/local/bin",
    }
end

Jalur yang dikembalikan ditambahkan ke daftar pemindaian walker hanya selama localhost pemindaian — mereka tidak berpengaruh padacontainer,directory, atau pemindaian. archive

Jalur pemindaian khusus platform

Ketika file yang Anda pedulikan tinggal di lokasi yang berbeda di Windows, macOS, dan Linux, cabang sbomgen.get_platform() dan kembalikan jalur yang sesuai untuk host:


function get_localhost_scan_paths()
    local platform = sbomgen.get_platform()

    if platform == sbomgen.platform.WINDOWS then
        local drive = sbomgen.get_system_drive()
        return {
            drive .. "/Program Files/MyApp/myapp.exe",
            drive .. "/Program Files (x86)/MyApp/myapp.exe",
        }
    end

    if platform == sbomgen.platform.DARWIN then
        return {"/Applications/MyApp.app/Contents/MacOS/myapp"}
    end

    -- Linux
    return {
        "/usr/bin/myapp",
        "/usr/local/bin/myapp",
    }
end

Pada Windows, gunakan sbomgen.get_system_drive() untuk menyelesaikan huruf drive sistem (misalnya,"C:") daripada hard-coding itu. Untuk jalur yang berasal dari variabel lingkungan seperti LOCALAPPDATA orPROGRAMFILES, iterasi sbomgen.get_env_vars() dan cari nilai dengan kunci. Lihat Referensi API Plugin untuk detailnya.

Plugin Koleksi

Plugin koleksi hanya membutuhkan collect() fungsinya. Semua fungsi lainnya adalah opsional.

collect(file_path)dipanggil sekali per file yang ditemukan oleh plugin penemuan berpasangan. Pola khasnya adalah:

Baca konten file menggunakan sbomgen.read_file() (untuk file kecil yang dimuat ke memori) atau sbomgen.open_file() (untuk file besar dibaca line-by-line).
Parse konten — pencocokan string untuk manifes sederhana, sbomgen.json_decode() untuk JSON, untuk XHTML, atau sbomgen.xml_decode() sbomgen.search_binary() untuk binari yang dikompilasi.
Publikasikan setiap paket yang ditemukan sbomgen.push_package() dengan menelepon dengan metadata paket.


-- REQUIRED: Called once per discovered file.
-- Parse the file and call sbomgen.push_package() for each package found.
function collect(file_path)
    local content, err = sbomgen.read_file(file_path)
    if err or not content then return end

    for line in content:gmatch("[^\r\n]+") do
        local name, version = line:match("^([%w%-%_%.]+)==(.+)$")
        if name and version then
            sbomgen.push_package({
                name = name,
                version = version,
                purl_type = "pypi",
                component_type = sbomgen.component_types.LIBRARY,
            })
        end
    end
end

collect()tidak mengembalikan nilai. Setiap push_package() panggilan membutuhkanname,purl_type, dancomponent_type. Lihat Referensi API Plugin untuk semua bidang yang didukung.

Melampirkan metadata ke komponen

Sbomgen mendukung dua cara untuk melampirkan metadata ke komponen paket: kualifikasi PURL dan properti CycloneDX. Mereka melayani tujuan yang berbeda, dan pilihan di antara mereka memiliki implikasi untuk bagaimana Amazon Inspector mengidentifikasi kerentanan dalam SBOM yang dihasilkan.

Mekanisme	Dimana itu muncul	Gunakan untuk
`qualifiers`	Di dalam URL paket (mis.,`pkg:deb/debian/curl@7.88.1?arch=amd64`)	Data yang merupakan bagian dari identitas paket
`properties`	Dalam array SBOM `components[].properties`	Metadata deskriptif yang tidak mengubah cara paket diidentifikasi

Rekomendasi: lebih suka properti CycloneDX (di bawah namespace Anda sendiri) untuk metadata kustom. Properti tidak mengubah identitas komponen, sehingga tidak dapat memengaruhi identifikasi kerentanan Amazon Inspector. Cadangan kualifikasi PURL untuk kasus di mana tipe PURL ekosistem Anda memerlukannya.

Kualifikasi PURL

Beberapa kualifikasi PURL memiliki arti semantik untuk Amazon Inspector dan memengaruhi identifikasi kerentanan. Misalnya, pada deb komponen Inspector menggunakan qualifier seperti arch dan distro untuk memilih feed kerentanan yang benar; pada generic komponen untuk binari yang dikompilasi, qualifier seperti go_toolchain atau mengidentifikasi toolchain yang digunakan. rust_toolchain Menyetel Inspector yang memenuhi syarat tidak mengenali, atau menghilangkan yang diharapkan, dapat menyebabkan kerentanan terlewatkan atau salah dikaitkan.

Lihat Apa itu URL paket? dalam panduan pengguna Amazon Inspector untuk konvensi kualifikasi yang diakui Inspector per jenis PURL.

Tetapkan kualifikasi melalui qualifiers tabel disbomgen.push_package():


sbomgen.push_package({
    name = "curl",
    version = "7.88.1",
    purl_type = "deb",
    namespace = "debian",
    component_type = sbomgen.component_types.LIBRARY,
    qualifiers = {
        arch = "amd64",
        distro = "debian-12",
    },
})

Hanya tetapkan kualifikasi ketika mereka selaras dengan harapan Inspektur untuk tipe PURL. Jika Anda perlu merekam metadata yang bukan bagian dari identitas paket, gunakan properti CycloneDX sebagai gantinya.

Properti CycloneDX

Properti CycloneDX adalah anotasi nilai kunci yang muncul dalam array SBOM. components[].properties Mereka menggambarkan komponen tanpa mempengaruhi bagaimana itu diidentifikasi, sehingga mereka adalah pilihan yang aman untuk metadata yang ditentukan plugin.

amazon:inspector:*Ruang nama disediakan untuk Amazon Inspector. Secara khusus:

amazon:inspector:sbom_generator:*— disediakan untuk sbomgen dan pemindai bawaannya.
amazon:inspector:sbom_scanner:*— disediakan untuk Amazon Inspector Scan API.

Penulis plugin tidak boleh mengeluarkan kunci di dalam ruang nama yang dicadangkan ini. Menulis ke dalamnya dapat mengganggu perilaku Inspektur dan dapat ditimpa. Untuk daftar lengkap kunci cadangan, lihat Menggunakan ruang nama CycloneDX dengan Amazon Inspector.

Gunakan namespace Anda sendiri (biasanya pengenal organisasi atau plugin Anda) saat mendefinisikan properti:


sbomgen.push_package({
    name = "requests",
    version = "2.28.1",
    purl_type = "pypi",
    component_type = sbomgen.component_types.LIBRARY,
    properties = {
        ["acme:python:manifest_path"] = file_path,
        ["acme:python:pinned"] = "true",
        ["acme:python:source"] = "requirements.txt",
    },
})

Aturan penamaan kunci

Kunci properti diproses oleh sbomgen sebagai berikut:

Kunci yang berisi titik dua digunakan kata demi kata di SBOM. Selalu sertakan setidaknya satu titik dua di kunci Anda sehingga Anda mengontrol namespace.
Kunci yang tidak mengandung titik dua secara otomatis diawali dengan amazon:inspector:sbom_generator: — menempatkannya di dalam namespace Inspector yang dicadangkan. Hindari bentuk ini untuk properti kustom.


properties = {
    ["acme:my_plugin:detected_via"] = "lockfile",  -- used as-is (recommended)
    detected_via                   = "lockfile",  -- becomes "amazon:inspector:sbom_generator:detected_via" (avoid)
}

sbomgen.properties.*Konstanta ada sehingga pemindai resmi memancarkan kunci yang konsisten di dalam namespace yang dicadangkan. Mereka bukan titik ekstensi untuk plugin khusus — gunakan namespace Anda sendiri sebagai gantinya.

Properti dan kualifikasi pada komponen anak

Bersarang children adalah komponen independen. Setiap anak memiliki tabelnya sendiri properties dan qualifiers tabelnya; metadata yang ditetapkan pada orang tua tidak menyebar ke anak-anak. Tetapkan nilai secara eksplisit pada setiap anak yang membutuhkannya.

Fungsi koleksi opsional

Fungsi	Default	Ganti saat...
`get_collector_name()`	`{ecosystem}`(misalnya,`python-pip`)	Anda ingin nama kolektor khusus
`get_collector_description()`	string kosong	Anda ingin deskripsi
`subscribe_to_event()`	Berasal dari jalur direktori	Anda memerlukan perutean acara khusus

Menjalankan Plugin Anda

Agar plugin menghasilkan metadata paket, sbomgen harus diberi artefak untuk memindai yang berisi file target plugin Anda (misalnya, direktori dengan, requirements.txtpackage.json, atau file manifes paket yang setara).

Penggunaan dasar


inspector-sbomgen <artifact type> <arguments> --plugin-dir /path/to/plugins

Contoh:


inspector-sbomgen directory --path /target -o /tmp/sbom.json --plugin-dir /path/to/plugins

Dengan pemindai asli dinonaktifkan (mode khusus Lua)


inspector-sbomgen directory --path /target --plugin-dir /path/to/plugins --disable-native-scanners -o sbom.json

Dengan logging verbose


inspector-sbomgen directory --path /target --plugin-dir /path/to/plugins --verbose -o sbom.json

Daftar Pemindai yang Tersedia

Gunakan list-scanners untuk melihat setiap pemindai yang tersedia untuk sbomgen. Ini termasuk pemindai asli bawaan, plugin Lua resmi apa pun yang dibundel dengan sbomgen, dan plugin Lua kustom apa pun yang Anda berikan melalui: --plugin-dir


inspector-sbomgen list-scanners --plugin-dir /path/to/plugins


┌─────────────────────┬────────┬───────────────────────────────┬─────────────────────────────┐
│    SCANNER NAME     │ SOURCE │            GROUPS             │         DESCRIPTION         │
├─────────────────────┼────────┼───────────────────────────────┼─────────────────────────────┤
│ curl                │ custom │ extra-ecosystems              │ Discovers curl version      │
│                     │        │ pkg-scanner                   │ header files (curlver.h)    │
├─────────────────────┼────────┼───────────────────────────────┼─────────────────────────────┤
│ python-requirements │ custom │ pkg-scanner                   │ Discovers requirements*.txt │
│                     │        │ programming-language-packages │ files for Python pip        │
│                     │        │                               │ packages                    │
└─────────────────────┴────────┴───────────────────────────────┴─────────────────────────────┘

Kolom SOURCE menunjukkan dari mana setiap pemindai berasal:

Sumber	Arti
`native`	Pemindai bawaan yang dibundel dengan sbomgen
`official`	Plugin Lua dibundel dengan sbomgen
`custom`	Plugin Lua yang disediakan pengguna dimuat melalui `--plugin-dir`

Berjalan list-scanners tanpa --plugin-dir masih termasuk keduanya native dan official pemindai - itu selalu tersedia. --plugin-dirBendera menambahkan custom pemindai Anda ke daftar.

Untuk mencantumkan hanya pemindai Lua tanpa pemindai asli:


inspector-sbomgen list-scanners --plugin-dir /path/to/plugins --disable-native-scanners

Pemilihan Pemindai

Plugin penemuan Lua berpartisipasi dalam model pemilihan pemindai yang sama dengan pemindai asli bawaan. Secara default, sbomgen menjalankan semua pemindai yang grupnya cocok dengan grup pemindai default untuk jenis artefak. Anda dapat mengganti ini dengan tiga bendera:

Jalankan hanya pemindai tertentu

Gunakan --scanners untuk menjalankan hanya pemindai bernama. Semua pemindai lainnya dikecualikan:


inspector-sbomgen directory --path /target \
    --plugin-dir /path/to/plugins \
    --scanners python-requirements \
    -o sbom.json

Ini hanya menjalankan python-requirements pemindai. Anda dapat meneruskan beberapa nama pemindai yang dipisahkan dengan koma, atau meneruskan nama grup pemindai (misalnya,programming-language-packages) untuk mengaktifkan setiap pemindai yang termasuk dalam grup tersebut.

Kecualikan pemindai tertentu

Gunakan --skip-scanners untuk mengecualikan pemindai bernama saat menjalankan yang lainnya:


inspector-sbomgen directory --path /target \
    --plugin-dir /path/to/plugins \
    --skip-scanners python-poetry \
    -o sbom.json

Ini menjalankan setiap pemindai default kecualipython-poetry. Seperti--scanners, bendera ini juga menerima nama grup, jadi passing --skip-scanners programming-language-packages menonaktifkan setiap pemindai di grup itu.

catatan

--scannersdan --skip-scanners saling eksklusif. Melewati keduanya menghasilkan kesalahan.

Tambahkan pemindai dari grup non-default

Set pemindai default tergantung pada jenis artefak yang dipindai (lihat matriks di Bagaimana kelompok mempengaruhi seleksi bawah). Pemindai yang grupnya bukan bagian dari set default untuk tipe artefak tidak akan berjalan kecuali Anda memilihnya. Gunakan --additional-scanners untuk menambahkan pemindai ke set default tanpa menggantinya:


inspector-sbomgen directory --path /target \
    --plugin-dir /path/to/plugins \
    --additional-scanners my-extra-scanner \
    -o sbom.json

Ini menjalankan setiap pemindai default untuk jenis artefak, plusmy-extra-scanner. Bendera menerima daftar nama pemindai atau nama grup yang dipisahkan koma, dan ditumpuk dengan set default daripada menggantinya. Gunakan list-scanners untuk memeriksa grup mana yang dimiliki pemindai.

Bagaimana kelompok mempengaruhi seleksi

get_scanner_groups()Fungsi dalam plugin penemuan Anda menentukan grup mana yang dimiliki pemindai. Apakah pemindai berjalan secara default tergantung pada kelompoknya dan jenis artefak yang dipindai. Matriks di bawah ini menunjukkan grup mana yang termasuk dalam set pemindai default untuk setiap jenis artefak:

Kelompok	`directory` / `archive`	`container`	`localhost`	`volume`	`binary`
`os`	—	✓	✓	✓	—
`programming-language-packages`	✓	✓	✓	✓	—
`binary`	✓	✓	—	—	✓
`extra-ecosystems`	—	✓	✓	✓	—
`dockerfile`	✓	✓	—	—	—
`custom`	✓	✓	✓	✓	✓
`certificate`	—	—	—	—	—
`machine-learning`	—	—	—	—	—
`pkg-scanner`	—	—	—	—	—

A ✓ berarti setiap pemindai dalam grup tersebut berjalan secara default untuk jenis artefak tersebut. A — berarti grup tidak dalam set default, jadi pemindainya hanya berjalan jika dipilih secara eksplisit melalui atau. --scanners --additional-scanners

Detail penting:

customselalu dalam set default - plugin khusus yang dimuat melalui --plugin-dir secara otomatis menerima custom grup, sehingga mereka berjalan secara default terlepas dari jenis artefak.
extra-ecosystemsadalah default untukcontainer,localhost, dan volume memindai, tetapi tidak untukdirectory,archive, atau binary memindai. Untuk jenis tersebut, Anda harus lulus --additional-scanners (dengan nama atau extra-ecosystems grup) untuk memasukkannya.
pkg-scannerbersifat informasional — ini menandai pemindai sebagai kolektor paket untuk ditampilkanlist-scanners, tetapi tidak dengan sendirinya menyebabkan pemindai berjalan. Pasangkan dengan grup eksekusi (misalnya,programming-language-packages) diget_scanner_groups().

Misalnya, plugin yang kembali {sbomgen.groups.EXTRA_ECOSYSTEMS, sbomgen.groups.PACKAGE_COLLECTOR} akan berjalan secara default pada pemindaian kontainer, localhost, dan volume, tetapi akan memerlukan --additional-scanners (atau--scanners) pada pemindaian direktori, arsip, dan biner.

Aturan Tabrakan Plugin

Sbomgen memberlakukan metadata unik di semua plugin yang dimuat untuk mencegah penimpaan diam dan memastikan integritas SBOM. Ketika tabrakan terdeteksi, plugin selanjutnya dilewati dan peringatan dicatat.

Apa yang diperiksa

Metadata	Lingkup	Pada tabrakan
Nama acara Discovery (`get_event_name`)	Semua plugin penemuan	Plugin kedua dilewati
Nama pemindai (`get_scanner_name`)	Semua plugin penemuan	Plugin kedua dilewati
Nama kolektor (`get_collector_name`)	Semua plugin koleksi	Plugin kedua dilewati

Apa yang diizinkan

Beberapa plugin koleksi dapat berlangganan acara yang sama melaluisubscribe_to_event(). Ini adalah pola fan-out yang dimaksudkan — satu plugin penemuan dapat memberi makan beberapa kolektor yang masing-masing melakukan hal yang berbeda (misalnya, satu mengekstrak paket, yang lain mendeteksi rahasia).

Menghindari tabrakan

Jika dua plugin menggunakan nama pemindai, nama acara, atau nama kolektor yang sama, yang kedua dimuat dilewati. Untuk mengatasi tabrakan, ganti nama metadata yang bertentangan dengan mendefinisikan fungsi penggantian yang sesuai di plugin Anda (,, atau). get_scanner_name() get_event_name() get_collector_name()

Contoh peringatan tabrakan


[custom:python-pip] SKIPPED: discovery event name "EventNameFoundPythonRequirements"
is already registered by [official:python-pip]. Each discovery plugin must have a
unique event name. Rename get_event_name() in your plugin to use a unique name.

Peringatan memberi tahu Anda plugin mana yang dilewati, apa yang bertabrakan, plugin mana yang sudah memiliki nama itu, dan fungsi mana yang harus diubah.

Debugging

Pencatatan konsol

Plugin dapat memancarkan pesan ke output konsol sbomgen menggunakan fungsi berikut:

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

Semua output log dari plugin secara otomatis diawali dengan sumber dan jalur plugin (misalnya,[custom:python-pip]), sehingga pesan dari plugin yang berbeda mudah dibedakan. log_info,log_warn, dan log_error selalu mencetak; log_debug hanya mencetak ketika sbomgen dipanggil dengan. --verbose


function discover()
    sbomgen.log_info("starting discovery")
    local files = sbomgen.find_files_by_name({"requirements.txt"})
    sbomgen.log_debug(string.format("matched %d files", #files))
    if #files == 0 then
        sbomgen.log_warn("no requirements.txt files found")
    end
    return files
end

Breakpoint

Gunakan sbomgen.breakpoint() untuk menjeda eksekusi plugin dan memblokir sampai Anda menekan Enter. Ini bertindak sebagai debugger kasar - menggabungkannya dengan pernyataan log untuk memeriksa status pada titik-titik tertentu.


function discover()
    local files = sbomgen.find_files_by_name({"requirements.txt"})

    sbomgen.log_info(string.format("about to inspect %d files", #files))
    sbomgen.breakpoint("before file inspection — press Enter to continue")

    local found = {}
    for _, f in ipairs(files) do
        if not f:match("[/\\]tests[/\\]") then
            table.insert(found, f)
        end
    end

    sbomgen.log_info(string.format("kept %d files after filtering", #found))
    sbomgen.breakpoint("after filtering — press Enter to continue")

    return found
end

Pesan breakpoint dicetak ke stderr. Eksekusi berhenti sampai Anda menekan Enter, memberi Anda waktu untuk meninjau output log.

Masalah umum

Gejala	Menyebabkan	Perbaiki
Plugin tidak dimuat	Hilang `init.lua`	Pastikan entrypoint ada pada kedalaman direktori yang benar
“kehilangan fungsi yang diperlukan”	Kesalahan ketik dalam nama fungsi	Periksa bahwa `get_scanner_nameget_scanner_description`,`get_scanner_groups`,`discover`,`get_event_name`, `get_localhost_scan_pathsget_collector_name`,`collect`,, `subscribe_to_event` didefinisikan
Plugin koleksi tidak pernah dipanggil	Ketidakcocokan nama acara	Verifikasi `get_event_name()` dan `subscribe_to_event()` kembalikan string yang sama
Tidak ada paket di SBOM	`push_package`tidak dipanggil atau bidang wajib hilang	Pastikan`name`,`purl_type`, dan `component_type` diatur dalam setiap `push_package` panggilan (termasuk anak-anak). Gunakan `sbomgen.component_types.*` konstanta.
Kesalahan runtime di plugin	Kesalahan Lua selama eksekusi	Periksa output sbomgen untuk pesan peringatan dengan detail kesalahan
“SKIPPED: nama acara penemuan... sudah terdaftar”	Plugin lain menggunakan nama acara yang sama	Ganti nama `get_event_name()` menjadi nilai unik
“SKIPPED: nama pemindai... sudah terdaftar”	Plugin lain menggunakan nama pemindai yang sama	Ganti nama `get_scanner_name()` menjadi nilai unik
“SKIPPED: nama kolektor... sudah terdaftar”	Plugin lain menggunakan nama kolektor yang sama	Ganti nama `get_collector_name()` menjadi nilai unik

Referensi API

Katalog fungsi lengkap dipertahankan dalam dokumen pendamping:

→ Referensi API Plugin

Referensi API mencakup setiap sbomgen.* fungsi (file I/O, utilitas biner, output paket, regex, parsing terstruktur, registri Windows, logging, debugging), testing.* API yang tersedia dalam file pengujian, semua konstanta bawaan (,,,platform) properties groupscomponent_types, dan global siklus hidup plugin.

Penanganan Kesalahan

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


local content, err = sbomgen.read_file(path)
if err then
    sbomgen.log_error("failed to read " .. path .. ": " .. err)
    return
end
-- content is safe to use here

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

Pembatasan Kotak Pasir

Plugin berjalan di VM Lua kotak pasir dengan akses perpustakaan standar terbatas:

Perpustakaan	Available	Catatan
`base`	✓	`dofile`, `loadfileloadstring`, dihapus
`string`	✓	Manipulasi string penuh
`table`	✓	Manipulasi meja penuh
`math`	✓	Perpustakaan matematika lengkap
`package`	✓	`require()`terbatas pada direktori plugin
`io`	✗	Gunakan `sbomgen.*` I/O fungsi sebagai gantinya
`os`	✗	Diblokir untuk keamanan
`debug`	✗	Diblokir untuk mencegah introspeksi VM
`coroutine`	✗	Tidak dimuat

Akses sistem file langsung melalui io.open atau os.execute tidak tersedia. Semua operasi file harus melalui sbomgen API, yang memastikan perilaku yang konsisten di seluruh jenis artefak dan mencegah plugin mengakses file di luar artefak.

require()dapat memuat modul hanya dari dalam pohon direktori plugin itu sendiri. Penjelajahan direktori induk seperti require("../shared") diblokir.

Anda dapat menggunakan require() untuk memuat modul pembantu dari dalam direktori plugin Anda:


my-ecosystem/
├── init.lua
└── helpers.lua


-- helpers.lua
local M = {}
function M.parse_version(s)
    return string.match(s, "(%d+%.%d+%.%d+)")
end
return M


-- init.lua
local helpers = require("helpers")

function subscribe_to_event() return "MyEvent" end

function collect(file_path)
    local content, err = sbomgen.read_file(file_path)
    if err then return end
    local version = helpers.parse_version(content)
    -- ...
end

Subdirektori dengan juga init.lua didukung:


my-ecosystem/
├── init.lua
└── parsers/
    └── init.lua


local parsers = require("parsers")

require()dibatasi untuk direktori plugin Anda. Anda tidak dapat memuat modul dari plugin atau jalur sistem lain. Pustaka Lua pihak ketiga (misalnya, dari LuaRocks) tidak didukung - hanya modul pembantu lokal dalam direktori plugin yang dapat dimuat.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Menggunakan ruang CycloneDX nama

Panduan pengujian plugin