Référence de l'API du plugin

Référence d'API complète pour les plugins Lua inspector-sbomgen. Pour un guide sur l'écriture de plugins, voirGuide du développeur de plugins. Pour les tests, voirGuide de test des plugins.

Présentation de

Toutes les fonctions fournies par l'exécution sont accessibles via la sbomgen table globale (E/S de fichiers, regex, journalisation, constantes, etc.). En outre, chaque plugin définit un petit ensemble de fonctions globales de haut niveau (discover,,, collect get_scanner_namesubscribe_to_event, etc.) que sbomgen appelle à des moments définis du cycle de vie du plugin. Ils sont documentés dansCycle de vie des plugins à l'échelle mondiale.

Dans les *_test.lua fichiers, sbomgen expose également un testing global qui permet aux auteurs de tests de piloter le pipeline discovery→collection et de faire des assertions. Consultez API de test.

Restrictions relatives au sandbox

Les plugins s'exécutent dans une machine virtuelle Lua en sandbox avec un accès restreint à la bibliothèque standard. Les modules de bibliothèque standard Lua suivants sont disponibles :

Modules	Remarques
base	Fonctions de base (printtype,tostring,tonumber,pairs,ipairs,pcall,error,select,unpack,rawget,rawset,, etc.). dofileloadfile, et loadstring sont supprimés.
string	Manipulation complète des chaînes (string.matchstring.findstring.format,string.gsub,,, etc.)
table	Manipulation complète du tableau (table.inserttable.removetable.sort,table.concat,,, etc.)
math	Bibliothèque mathématique complète (math.floormath.max,math.min,, etc.)
package	require()est disponible mais limité aux modules situés dans la propre arborescence de répertoires du plugin. La traversée du répertoire parent (require("../shared")) est bloquée. package.cpathet package.path sont dédouanés.

Les modules de bibliothèque standard suivants sont explicitement interdits pour des raisons de sécurité et de stabilité :

Modules	Motif
io	L'accès direct au système de fichiers est bloqué. Toutes les opérations sur les fichiers doivent passer par des sbomgen.* fonctions qui passent par l'interface d'artefact pour un comportement cohérent entre les types d'artefacts (répertoire, conteneur, volume, etc.).
os	Les opérations au niveau du système (os.execute,os.remove,os.rename,os.getenv, etc.) sont bloquées pour empêcher les plugins de modifier le système hôte.
debug	La bibliothèque de débogage est bloquée pour empêcher l'inspection ou la modification des composants internes de la machine virtuelle Lua.
coroutine	Les coroutines ne sont pas chargées.

Ces modules ne figurent pas dans la liste des modules autorisés de la machine virtuelle et ne sont pas accessibles aux plugins.

Note

Important : Tous les fichiers I/O doivent passer par sbomgen.* des fonctions (par exemplesbomgen.read_file,sbomgen.open_file,sbomgen.get_file_list). L'utilisation io.open ou tout accès direct au système de fichiers provoquera une erreur d'exécution. L'sbomgenAPI garantit que les plugins interagissent avec la couche d'abstraction des artefacts, qui fournit un comportement cohérent lors de l'analyse d'un répertoire, d'une image de conteneur, d'une archive ou d'un volume.

Cycle de vie des plugins à l'échelle mondiale

Un plugin est un fichier Lua nommé init.lua qui définit certaines fonctions globales de haut niveau. Ces globals ne sont pas sur la sbomgen table, ce sont des fonctions que le plugin définit pour que sbomgen puisse appeler. L'ensemble des valeurs globales valides diffère entre les plugins de découverte et les plugins de collecte. Pour chaque fonction ci-dessous, si le plugin l'omet, la valeur par défaut indiquée dans le tableau est utilisée.

Plug-ins de découverte

Fonction	Arité	Obligatoire	Par défaut (en cas d'omission)	Description
discover()	0	Oui	—	Renvoie les fichiers trouvés par ce plugin. Renvoie une table séquentielle de chaînes de chemins (mode événement unique) ou une table saisie par des chaînes de noms d'événements dont les valeurs sont des tables de chemins (mode multi-événements).
get_event_name()	0	Non	"lua:{platform}/{category}/{ecosystem}"	Renvoie le nom de l'événement sous lequel les fichiers sont publiés. Doit être unique pour tous les plugins de découverte.
get_scanner_name()	0	Non	nom du répertoire de l'écosystème	Renvoie le nom d'affichage du scanner. Doit être unique pour tous les plugins de découverte.
get_scanner_description()	0	Non	"Lua discovery plugin: {ecosystem}"	Renvoie une description lisible par l'homme.
get_scanner_groups()	0	Non	Dérivé du répertoire des catégories (voir le guide du développeur)	Renvoie un tableau des chaînes de groupes de scanners. Utilisez sbomgen.groups.* des constantes.
get_localhost_scan_paths()	0	Non	—	Renvoie un tableau des file/directory chemins à inclure lors de l'analyse d'un artefact localhost. Consulté uniquement pour les localhost scans.

Plug-ins de collecte

Fonction	Arité	Obligatoire	Par défaut (en cas d'omission)	Description
collect(file_path)	1	Oui	—	Appelé une fois par fichier publié lors de l'événement auquel vous êtes abonné. Analysez le fichier et émettez les résultats viasbomgen.push_package(). Ne renvoie rien.
subscribe_to_event()	0	Non	"lua:{platform}/{category}/{ecosystem}"	Renvoie le nom de l'événement auquel le collecteur est abonné. Doit correspondre au plugin de découverte correspondantget_event_name().
get_collector_name()	0	Non	nom du répertoire de l'écosystème	Renvoie le nom d'affichage du collecteur. Doit être unique dans tous les plugins de collection.
get_collector_description()	0	Non	""(vide)	Renvoie une description lisible par l'homme.

E/S de fichiers

Toutes les opérations sur les fichiers doivent passer par l'sbomgen.*API. L'accès direct au système de fichiers via la io bibliothèque de Lua n'est pas disponible (voirRestrictions relatives au sandbox). Les I/O fonctions de sbomgen fichier passent par l'interface artefact, ce qui garantit que votre plug-in fonctionne de la même manière, qu'il s'agisse de scanner un répertoire sur le disque, une image de conteneur, une archive compressée ou un volume monté.

sbomgen.get_file_list()

Renvoie tous les chemins de fichiers de l'artefact sous forme de table de chaînes.

• Renvoie : {string, ...} — table des chaînes de chemin de fichier absolues

• Performance : cette fonction copie chaque chemin de fichier de l'artefact dans la machine virtuelle Lua sous forme de chaîne Lua. Sur des artefacts volumineux (par exemple, un scan localhost avec plus de 300 000 fichiers), cela prend à lui seul plusieurs secondes. L'itération de la table renvoyée dans Lua string.match() augmente la charge de travail : une analyse complète peut prendre plus de 15 secondes. Plus il y a de fichiers dans l'artefact, plus votre plugin sera lent.

Note

Privilégiez ces alternatives ciblées dans la mesure du possible :

Fonction	À utiliser lorsque...
sbomgen.find_files_by_name()	Vous connaissez le (s) nom (s) exact (s) de fichier (par exemple"requirements.txt","curl")
sbomgen.find_files_by_name_icase()	Comme ci-dessus, mais sans distinction majuscules/majuscules
sbomgen.find_files_by_suffix()	Vous devez faire correspondre les suffixes de chemin (par exemple,,"/pom.properties") "curlver.h"
sbomgen.find_files_by_path_regex()	Vous avez besoin d'une correspondance regex complète
sbomgen.glob_find_files()	Vous avez besoin d'une correspondance des noms de base de type global

Ces fonctions effectuent une mise en correspondance en dehors de la machine virtuelle Lua et ne renvoient que les chemins correspondants, en moins d'une milliseconde, même sur des artefacts de 300 000 fichiers. À utiliser get_file_list() uniquement lorsque votre logique de correspondance ne peut être exprimée avec aucun des éléments ci-dessus.

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

Lit l'intégralité du contenu d'un fichier et le renvoie sous forme de chaîne.

• Retours : string, err

• En cas de panne : 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)

Ouvre un fichier pour des lectures en continu. Renvoie un FileHandle objet. Utilisez-le pour les fichiers volumineux où le chargement de l'intégralité du contenu en mémoire n'est pas pratique.

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

Renvoie les fichiers correspondant à un modèle Go filepath.Match glob. Le modèle est comparé au nom de fichier de base.

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

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

Utilisez sbomgen.get_file_list() with string.match pour une correspondance complète des modèles de chemin.

sbomgen.find_files_by_name(names)

Renvoie les fichiers dont le nom de base (dernier composant du chemin) correspond exactement à l'un des noms donnés. L'itération et la comparaison ont lieu dans Go, ce qui les rend nettement plus rapides que sbomgen.get_file_list() dans Lua.

• Paramètres : names — table de chaînes (noms de base correspondants)

• Renvoie : {string, ...} — chemins de fichiers correspondants (aucun tuple d'erreur)

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)

Renvoie les fichiers dont le nom de base correspond à l'un des noms donnés, en ignorant les majuscules et minuscules. Par exemple, des "version" allumettes VERSIONVersion, etversion. Par exemplefind_files_by_name, la correspondance se produit en dehors de la machine virtuelle Lua.

• Paramètres : names — table de chaînes (noms de base correspondants, sans distinction majuscules/minuscules)

• Renvoie : {string, ...} — chemins de fichiers correspondants (aucun tuple d'erreur)

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)

Renvoie les fichiers dont le chemin complet (forward-slash-normalized) se termine par l'un des suffixes donnés. Par exemplefind_files_by_name, la correspondance se produit en dehors de la machine virtuelle Lua.

• Paramètres : suffixes — table de chaînes (suffixes de chemin correspondants)

• Renvoie : {string, ...} — chemins de fichiers correspondants (aucun tuple d'erreur)

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)

Renvoie les fichiers dont forward-slash-normalized le chemin correspond à l'un des modèles regex Go (RE2) donnés. La mise en correspondance s'effectue en dehors de la machine virtuelle Lua, ce qui la rend efficace sur les grandes listes de fichiers.

• Paramètres : patterns — table des chaînes regex Go

• Renvoie : {string, ...} — chemins de fichiers correspondants (aucun tuple d'erreur)

• Déclenche : une erreur Lua si un modèle ne parvient pas à être compilé

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

Performance : find_files_by_* contre get_file_list

Pour les plugins de découverte find_files_by_namefind_files_by_suffix, préférez ou trop find_files_by_path_regex itérer get_file_list() dans Lua. Lors d'un scan localhost avec 300 000 fichiers, l'itération de la liste de fichiers dans Lua string.match() prend environ 15 secondes, et se find_files_by_name termine en moins d'une milliseconde. La différence est que get_file_list() chaque chemin de fichier est copié dans la machine virtuelle Lua sous forme de chaîne, puis Lua interprète la boucle et le modèle correspondant à chacun d'eux. Les find_files_by_* fonctions effectuent la mise en correspondance en dehors de la machine virtuelle Lua et ne renvoient que les chemins correspondants, évitant ainsi à la fois la surcharge de copie et d'interprétation par chemin.

À utiliser get_file_list() uniquement lorsque vous avez besoin d'une logique de correspondance personnalisée qui ne peut pas être exprimée sous forme de nom de base, de suffixe ou de correspondance régulière.

sbomgen.read_dir(path)

Répertorie les entrées d'un répertoire.

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

Renvoie les métadonnées relatives à un fichier.

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

Lit une seule entrée depuis une archive ZIP, JAR ou WAR.

• Retours : string, err

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

sbomgen.search_binary(path, regex)

Analyse un fichier en tant que binaire ELF, PE ou Mach-O et recherche dans la constant/variable section par défaut une correspondance regex Go.

• Renvoie : string|nil, err — la chaîne correspondante, ou zéro si aucune correspondance

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

Analyse un fichier en tant que binaire ELF, PE ou Mach-O et renvoie toutes les correspondances uniques du premier groupe de capture depuis la section par défaut. constant/variable Passez n pour limiter les résultats.

• Renvoie : {string, ...}|nil, err — table des chaînes correspondantes, ou zéro si aucune correspondance

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)

Recherche dans l'intégralité du fichier binaire la première correspondance regex, sans se limiter à une section spécifique. À utiliser lorsque la recherche basée sur les sections (search_binary) est insuffisante, par exemple lorsque les chaînes de version se trouvent dans des sections non standard.

• Renvoie : string|nil, err — la chaîne correspondante, ou zéro si aucune correspondance

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

FileHandle Méthodes

FileHandle les objets sont renvoyés parsbomgen.open_file().

fh:read_line()

Lit la ligne suivante (sans le caractère de nouvelle ligne). Retours nil à l'EOF.

• Retours : string|nil, err

fh:read(n)

Lit jusqu'à un n nombre d'octets. Retours nil à l'EOF.

• Retours : string|nil, err

fh:close()

Ferme le descripteur de fichier. Fermez toujours les poignées lorsque vous avez terminé.

Utilitaires binaires

sbomgen.sha256(path)

Renvoie le hachage SHA-256 codé en hexadécimal du contenu d'un fichier.

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

Vérifie si un fichier contient chacun des modèles d'octets donnés. Renvoie une table de booléens dans le même ordre que les modèles d'entrée.

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

Analyse les ressources d'une version de Windows PE à partir d'un fichier binaire. Renvoie une table avec des champs de version, ou nil, err si le fichier n'est pas un binaire PE ou ne possède aucune ressource de version.

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

Les file_version champs product_version et proviennent de la FixedFileInfo structure PE, formatés comme"major.minor.build.revision". Le string_table champ est une table imbriquée saisie par un code local (par exemple, "040904B0" pour l'Unicode anglais américain). Chaque localisation correspond à un tableau de name/value paires tiré du PE StringFileInfo (ProductVersionProductName,FileDescription,, etc.). Un binaire PE peut exposer un ou plusieurs paramètres régionaux.

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)

Enveloppe pratique qui renvoie uniquement la chaîne de version du produit à partir d'un binaire PE. FixedFileInfo C'est équivalent à appeler get_pe_version_info(path) et à lireproduct_version.

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

Enveloppeur pratique qui renvoie uniquement la chaîne de version du fichier à partir d'un binaire PE. FixedFileInfo C'est équivalent à appeler get_pe_version_info(path) et à lirefile_version.

• Retours : string, err

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

Sortie du package

sbomgen.push_package(pkg)

Envoie une recherche de package dans le SBOM. Disponible uniquement dans les plugins de collection.

Le pkg tableau prend en charge les champs suivants :

Champ	Type	Obligatoire	Description
name	chaîne	Oui	Nom du package
version	chaîne	Non	Chaîne de version résolue
namespace	chaîne	Non	espace de noms PURL (par exemple,,"curl") "wordpress/plugin"
purl_type	chaîne	Oui	Type de URL (par exemple,"pypi","npm", "cargo""deb","generic")
component_type	chaîne	Oui	Type de composant CycloneDx ; utilisez des sbomgen.component_types.* constantes (par exemple,) sbomgen.component_types.LIBRARY
qualifiers	table	Non	Qualificateurs PURL sous forme de paires clé-valeur (apparaissent dans l'URL du package)
properties	table	Non	Propriétés des composants CycloneDx sous forme de paires clé-valeur (voir) Propriétés de CycloneDx
children	table	Non	Packages enfants imbriqués, chacun ayant la même forme que pkg (les champs obligatoires sont validés de manière récursive)

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

Propriétés de CycloneDx

Les propriétés CycloneDX sont des métadonnées clé-valeur associées à un composant dans le SBOM. Ils sont distincts des qualificatifs PURL :

• qualifiers— Qualifications PURL. Ils font partie de la chaîne URL du package (par exemple,pkg:deb/debian/curl@7.88.1?arch=amd64). Certains qualificatifs PURL ont une signification sémantique pour Amazon Inspector et influencent l'identification des vulnérabilités. Voir Qu'est-ce qu'une URL de package ? pour les conventions par type de l'inspecteur.

• properties— Propriétés du composant CycloneDx. Ils apparaissent dans le components[].properties tableau du SBOM et ne modifient pas la façon dont le composant est identifié.

Espaces de noms réservés

La amazon:inspector:* famille d'espaces de noms de propriétés CycloneDX est réservée à Amazon Inspector :

• amazon:inspector:sbom_generator:*— utilisé par sbomgen et ses scanners intégrés.

• amazon:inspector:sbom_scanner:*— utilisé par l'API Amazon Inspector Scan.

Les propriétés définies par le plugin ne doivent pas utiliser ces espaces de noms. L'écriture dans un espace de noms réservé peut masquer ou entrer en conflit avec les valeurs sur lesquelles repose Inspector, et le SBOM qui en résulte peut être mal interprété lors de l'identification de la vulnérabilité. Consultez la section Utilisation des espaces de noms CycloneDX avec Amazon Inspector pour obtenir la liste complète des clés réservées.

Principales règles de dénomination

Les clés de propriété transmises sbomgen.push_package() sont traitées comme suit :

Clé de saisie	Clé résultante dans SBOM	Recommandé pour les plugins personnalisés ?
Contient : (par exemple,acme:my_plugin:field)	Verbatim utilisé	Oui, placez chaque propriété définie par le plugin dans votre propre espace de noms
Non : (par exemple,field)	Préfixé automatiquement à amazon:inspector:sbom_generator:field	Non, cela écrit dans un espace de noms réservé

Incluez toujours au moins deux points dans les clés de propriété que vous définissez. Utilisez un espace de noms propre à votre organisation ou à votre plugin (par exempleacme: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",
}

Propriétés définies par sbomgen

Sbomgen peut associer ses propres propriétés à chaque composant qu'il émet. Ces valeurs proviennent de l'espace de amazon:inspector:sbom_generator:* noms réservé et ne doivent pas être produites par des plugins. Comportement d'exécution observé :

• source_pathest toujours ajouté par sbomgen.

• source_file_scanneret source_package_collector sont ajoutés lorsqu'ils --enable-debug-props sont activés.

La taxonomie complète des clés réservées est disponible dans le guide de l'utilisateur d'Amazon Inspector : Using CyclonedX namespaces with Amazon Inspector.

Constantes de propriété

Les constantes de clé de propriété intégrées sont disponibles viasbomgen.properties. Chaque constante ci-dessous est convertie en une clé dans l'espace de amazon:inspector:sbom_generator:* noms réservé. Ces constantes existent de telle sorte que les scanners intégrés de sbomgen émettent des clés de propriété cohérentes. Ce ne sont pas des points d'extension pour les plugins personnalisés : leur utilisation dans un plugin personnalisé écrit dans un espace de noms réservé, qui peut masquer les valeurs sur lesquelles repose Inspector. Voir Espaces de noms réservés ci-dessus.

Les auteurs de plugins personnalisés doivent définir les propriétés sous leur propre espace de noms (par exempleacme:my_plugin:*) plutôt que de réutiliser ces constantes.

Constante	Valeur résolue
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

Groupes de scanners

Les plugins Discovery doivent déclarer leurs groupes de scanners viaget_scanner_groups(). Les groupes classent les scanners par catégories et permettent aux utilisateurs d'activer ou de désactiver des catégories de manière sélective. Les constantes sont disponibles via sbomgen.groups :

Constante	Valeur	Description
sbomgen.groups.OS	"os"	gestionnaires de paquets du système d'exploitation (dpkg, rpm, etc.)
sbomgen.groups.PROGRAMMING_LANGUAGE	"programming-language-packages"	Gestionnaires de packages linguistiques (pip, npm, maven, etc.)
sbomgen.groups.BINARY	"binary"	Analyse binaire compilée (Go, Rust)
sbomgen.groups.PACKAGE_COLLECTOR	"pkg-scanner"	Collecte générale des colis
sbomgen.groups.EXTRA_ECOSYSTEMS	"extra-ecosystems"	Écosystèmes supplémentaires (curl, nginx, etc.)
sbomgen.groups.CERTIFICATE	"certificate"	Numérisation des certificats
sbomgen.groups.CUSTOM	"custom"	Ajouté automatiquement à tous les plugins personnalisés chargés via --plugin-dir
sbomgen.groups.MACHINE_LEARNING	"machine-learning"	Détection de modèles d'apprentissage automatique

Exemple :

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

Constantes de type de composant

Le component_type champ push_package() doit être l'un des types de composants de CycloneDX 1.5. Les constantes sont disponibles via sbomgen.component_types :

Constante	Valeur
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"

Exemple :

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

Constantes de plate-forme

Constantes à comparer avecsbomgen.get_platform(). Disponible via sbomgen.platform :

Constante	Valeur
sbomgen.platform.LINUX	"linux"
sbomgen.platform.WINDOWS	"windows"
sbomgen.platform.DARWIN	"darwin"

Exemple :

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

Informations sur l'artifact

sbomgen.get_platform()

Renvoie la chaîne de la plateforme d'exécution (par exemple"linux","windows",,"darwin").

sbomgen.get_artifact_type()

Renvoie le type d'artefact scanné (par exemple,"directory","archive").

sbomgen.should_collect_licenses()

Renvoie true si l'utilisateur a activé la collecte de licences via--collect-licenses.

sbomgen.get_env_vars()

Renvoie les variables d'environnement de l'artefact sous forme de table d'{key, value}entrées.

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

Renvoie la lettre du lecteur système (par exemple,"C:") à partir de l'environnement de l'artefact. Lit la variable d'SystemDriveenvironnement, qui est définie par défaut "C:" si elle n'est pas définie. C'est l'équivalent Lua de. strutils.GetSystemDriverLetter()

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

Informations sur le système

Ces fonctions renvoient des métadonnées relatives au système d'exploitation et au matériel de l'artefact. Les valeurs peuvent être des chaînes vides si les informations ne sont pas disponibles (par exemple, lors de l'analyse d'un répertoire sans métadonnées du système d'exploitation).

Fonction	Renvoie
sbomgen.get_os_name()	Nom du système d'exploitation (par exemple"Ubuntu",,"Alpine Linux")
sbomgen.get_os_version()	Version du système d'exploitation (par exemple"22.04",,"3.18")
sbomgen.get_os_codename()	Nom de code du système d'exploitation (par exemple,,"jammy") "bookworm"
sbomgen.get_os_id()	Identifiant du système d'exploitation (par exemple"ubuntu",,"alpine")
sbomgen.get_kernel_name()	Nom du noyau (par exemple,"Linux")
sbomgen.get_kernel_version()	Chaîne de version du noyau
sbomgen.get_cpu_arch()	Architecture du processeur (par exemple"x86_64","aarch64")
sbomgen.get_hostname()	Nom d'hôte du système

Expressions régulières

Les modèles intégrés de Lua ne disposent pas de fonctionnalités telles que l'alternance (|), les plages de quantification ({n,}) et le lookahead. Pour combler cette lacune, sbomgen expose directement le package de regexp Go. Ces fonctions utilisent la syntaxe Go regex (RE2), et non les modèles Lua.

sbomgen.regex_find(str, pattern)

Renvoie la première correspondance d'un modèle de regex Go, ou en l'nilabsence de correspondance.

• Retours : string|nil, err

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

sbomgen.regex_match(str, pattern)

Renvoie les groupes de capture issus de la première correspondance. L'indice 1 correspond à la correspondance complète, les groupes de capture 2+ sont des groupes de capture.

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

Renvoie toutes les correspondances qui ne se chevauchent pas. Passer n pour limiter les résultats (par défaut : tous).

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

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

sbomgen.regex_replace(str, pattern, replacement)

Remplace toutes les allumettes. La chaîne de remplacement peut être utilisée $1$2, etc. pour les références de groupes de capture.

• Retours : string, err

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

Quand utiliser les modèles regex ou Lua

Utilisez lestring.match/intégré de Lua string.find pour créer des modèles simples : ils sont plus rapides et ne nécessitent pas d'échapper aux barres obliques inverses. À utiliser sbomgen.regex_* lorsque vous avez besoin de :

• Alternance : (foo|bar)

• Gammes de quantificateurs : \d{8,}

• Classes de caractères complexes non exprimables dans les modèles Lua

Analyse syntaxique structurée

Sbomgen propose des aides légères pour décoder les formats de texte structurés directement dans les tables Lua.

sbomgen.json_decode(str)

Analyse une chaîne JSON dans une table Lua.

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

Analyse une chaîne XML pour en faire une table Lua.

• Retours : table|nil, err

Les valeurs XML utilisent la forme suivante :

• _name— nom de l'élément

• _attr— table attributaire, lorsqu'elle est présente

• _text— contenu du texte découpé, le cas échéant

• indices numériques 1..n — éléments secondaires

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)

Registre Windows

Ces fonctions fournissent un accès en lecture seule au registre Windows. Sur les artefacts autres que Windows, registry_open_key renvoie une erreur. L'accesseur de registre est initialisé paresseusement lors de la première utilisation et prend en charge à la fois l'accès direct à l'API Windows (analyses localhost sous Windows) et l'analyse syntaxique REGF basée sur des fichiers (analyses de conteneurs/volumes).

sbomgen.registry_open_key(path)

Ouvre une clé de registre. Renvoie un descripteur de clé qui doit être fermé parregistry_close.

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

Lit une valeur de chaîne à partir d'une clé de registre ouverte.

• Retours : string, err

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

sbomgen.registry_get_integer(key, value_name)

Lit une valeur entière à partir d'une clé de registre ouverte.

• Retours : number, err

sbomgen.registry_get_strings(key, value_name)

Lit une valeur multichaîne (REG_MULTI_SZ) à partir d'une clé de registre ouverte. Renvoie une table de chaînes de caractères.

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

Renvoie tous les noms de sous-clés sous une clé de registre ouverte.

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

Ferme un descripteur de clé de registre. Les poignées à clés sont également fermées automatiquement par le ramasse-miettes, mais une fermeture explicite est recommandée.

Logging

Les messages du journal sont écrits sur la sortie de la console de sbomgen. Chaque message émis par un plugin est automatiquement préfixé avec le label source et l'écosystème du plugin, par exemple :

[custom:python-pip] Parsing requirements.txt

log_infolog_warn, et imprimez log_error toujours. log_debugne s'affiche que lorsque sbomgen est invoqué avec. --verbose

Fonction	Niveau	Visible par défaut ?
sbomgen.log_debug(message)	DEBUG	Non, nécessite --verbose
sbomgen.log_info(message)	INFO	Oui
sbomgen.log_warn(message)	WARN	Oui
sbomgen.log_error(message)	ERROR	Oui

À utiliser string.format pour les messages formatés :

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

Fonctions de débogage

sbomgen.breakpoint(message)

Imprime message sur stderr et bloque l'exécution jusqu'à ce que l'utilisateur appuie sur Entrée. S'il message est omis, imprime un message par défaut.

Utilisez-le comme un débogueur rudimentaire en plaçant des points d'arrêt à des points clés de votre plugin et en l'exécutant --verbose pour voir le résultat du journal environnant.

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

API de test

Les fonctions du testing tableau global ne sont disponibles que dans les fichiers de test du plugin (*_test.lua), chargés parinspector-sbomgen plugin test. Ils ne sont pas disponibles au moment de l'exécution dans les plugins de découverte ou de collecte. L'sbomgen.*API complète est également disponible dans les fichiers de test, mais les sbomgen.* fonctions qui nécessitent un artefact (par exemplesbomgen.read_file()) ne produisent des résultats significatifs que lorsqu'elles sont appelées depuis un scan. Pour un guide narratif, consultez leGuide de test des plugins.

Fonctions de numérisation

Chaque fonction de numérisation crée un artefact du type donné, exécute le pipeline de découverte → de collecte du plugin actuel par rapport à celui-ci et renvoie les résultats obtenus. L'pathargument est résolu par rapport au répertoire du fichier de test.

Fonction	Type d'Artifact
testing.scan_directory(path)	Annuaire
testing.scan_archive(path)	Répertoire (alias descan_directory)
testing.scan_localhost(path)	Hôte local
testing.scan_binary(path)	Binaire
testing.scan_volume(path)	Volume
testing.scan_container(path)	Conteneur

Tous les six renvoient un tableau de résultats avec la forme ci-dessous.

Forme du résultat

Chaque table de recherche projette uniquement les champs répertoriés ci-dessous. En particulier, namespace et ils ne purl_type sont pas projetés séparément, ils sont incorporés dans la purl chaîne complète.

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)

Assertions

Fonction	Signature	Description
testing.assert_equals	(expected: any, actual: any, message?: string)	Échoue sitostring(expected) ~= tostring(actual).
testing.assert_not_equals	(expected: any, actual: any, message?: string)	Échoue sitostring(expected) == tostring(actual).
testing.assert_true	(value: any, message?: string)	Échoue si value c'est le cas false ounil.
testing.assert_false	(value: any, message?: string)	Échoue si value ce n'est pas false le cas et nonnil.
testing.assert_nil	(value: any, message?: string)	Échoue si value ce n'est pas le casnil.
testing.assert_not_nil	(value: any, message?: string)	Échoue si value c'est le casnil.
testing.assert_contains	(haystack: string, needle: string, message?: string)	Échoue s'haystackil ne contient pas needle (correspondance de sous-chaîne).
testing.assert_matches	(str: string, pattern: string, message?: string)	Échoue s'stril ne correspond pas à l'expression régulière Go (RE2) donnée.
testing.assert_length	(tbl: table, expected: integer, message?: string)	Échoue s'#tblil n'est pas égalexpected.

Flux de contrôle

Fonction	Signature	Description
testing.fail	(message: string)	Échoue immédiatement le test en cours avec le message donné.
testing.skip	(message: string)	Ignore le test en cours. Le résultat est indiqué comme ignoré et non comme ayant échoué.

Découverte des tests

Toute fonction Lua globale dont le nom commence par test_ dans un fichier correspondant *_test.lua est traitée comme un test. Le fichier de test doit être placé à côté et init.lua à la {phase}/{platform}/{category}/{ecosystem}/ profondeur normale. Les données du montage sont _testdata/ placées à côté du fichier de test ; le lanceur n'y accède pas _testdata/ lorsqu'il recherche des fichiers de test.

Gestion des erreurs

Les fonctions d'API qui peuvent échouer renvoient deux valeurs :value, err. Sur le succès, err c'estnil. En cas d'échec, la première valeur err est nil et reste une chaîne d'erreur.

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

Si un plugin génère une erreur Lua non gérée, sbomgen enregistre un avertissement et passe au fichier ou au plugin suivant. Les autres plugins ne sont pas concernés.