Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Référence de l'API du plugin

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

Vue d’ensemble

Toutes les fonctions fournies par l'exécution sont accessibles via la sbomgen table globale (fichier I/O, regex, journalisation, constantes, etc.). En outre, chaque plug-in définit un petit ensemble de fonctions globales de premier niveau (discover,,, collect get_scanner_namesubscribe_to_event, etc.) que sbomgen appelle à des moments définis du cycle de vie du plug-in. Ils sont documentés dansGlobals du cycle de vie des plugins.

Dans les *_test.lua fichiers, sbomgen expose également un testing global qui permet aux auteurs de tests de piloter le pipeline de découverte → 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 bac à sable avec un accès standard restreint à la bibliothèque. Les modules de bibliothèque standard Lua suivants sont disponibles  :

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

Ces modules ne figurent pas dans la liste d'autorisation de la machine virtuelle et ne sont pas accessibles par les plugins.

Globals du cycle de vie des plugins

Un plugin est un fichier Lua nommé init.lua qui définit certaines fonctions globales de premier niveau. Ces variables globales ne sont pas sur la sbomgen table. Ce sont des fonctions que le plugin définit pour que sbomgen puisse les appeler. L'ensemble de 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, c'est la valeur par défaut indiquée dans le tableau qui est utilisée.

Plug-ins Discovery

Plug-ins de collecte

Dossier I/O

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 fichiers passent par l'interface d'artefact, garantissant que votre plug-in fonctionne de manière identique, qu'il s'agisse de scanner un répertoire sur disque, une image de conteneur, une archive compressée ou un volume monté.

Limite d'accès aux fichiers

Les fonctions de sbomgen.* fichier limitent les lectures à l'artefact figurant dans l'inventaire. Un chemin qui se résout en dehors de la racine de l'artefact, par exemple par ../ traversée, est rejeté et l'appel renvoie une erreur au lieu de lire le système de fichiers hôte. Cela s'applique à read_fileopen_file,read_dir,file_stat, et aux binary/hash aides qui empruntent un chemin.

L'exception est le type d'localhostartefact, qui répertorie l'hôte lui-même ; dans ce cas, le système de fichiers hôte est l'artefact, les lectures ne sont donc pas limitées à une racine plus étroite.

Cette limite ne régit que les lectures de fichiers. Cela ne limite pas ce qu'un plugin écrit dans le SBOM — voir. Le contenu du SBOM n'est pas assaini

sbomgen.get_file_list ()

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

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

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

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

sbomgen.open_file (chemin)

Ouvre un fichier pour les lectures en streaming. Renvoie un FileHandle objet. Utilisez cette option pour les fichiers volumineux pour lesquels le chargement de l'intégralité du contenu en mémoire n'est pas pratique.

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 (modèle)

Renvoie les fichiers correspondant à un modèle Go filepath.Match glob. Le modèle est comparé au nom de fichier de base. Les liens symboliques sont ignorés ; seuls les fichiers concrets sont renvoyés.

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

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

sbomgen.find_files_by_name (noms)

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

local curl_bins = sbomgen.find_files_by_name({"curl", "curl.exe"})
local headers = sbomgen.find_files_by_name({"curlver.h"})

sbomgen.find_files_by_name_icase (noms)

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

local version_files = sbomgen.find_files_by_name_icase({"version"})
local war_files = sbomgen.find_files_by_name_icase({"jenkins.war"})

sbomgen.find_files_by_suffixe (suffixes)

Renvoie les fichiers dont le chemin complet (normalisé par barre oblique) 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.

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 (modèles)

Renvoie les fichiers dont le chemin normalisé par barre oblique correspond à l'un des modèles d'expression régulière Go (RE2) donnés. La correspondance s'effectue en dehors de la machine virtuelle Lua, ce qui la rend efficace sur les listes de fichiers volumineuses.

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

Performance : find_files_by_* par rapport à get_file_list

Pour les plugins de découverte find_files_by_namefind_files_by_suffix, préférez ou find_files_by_path_regex plutôt que d'itérer get_file_list() en Lua. Lors d'un scan localhost contenant 300 000 fichiers, l'itération de la liste des fichiers dans Lua string.match() prend environ 15 secondes, alors qu'elle se find_files_by_name termine en moins d'une milliseconde. La différence est que chaque chemin de fichier est get_file_list() copié dans la machine virtuelle Lua sous forme de chaîne, puis Lua interprète la correspondance entre la boucle et le modèle pour chacun d'eux. Les find_files_by_* fonctions effectuent la correspondance en dehors de la machine virtuelle Lua et renvoient uniquement les chemins correspondants, évitant ainsi à la fois la charge 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 (chemin)

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

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

Renvoie les métadonnées d'un fichier.

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 (chemin, chemin_entrée)

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

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

sbomgen.search_binary (chemin, regex)

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

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

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

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

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 (chemin, regex)

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

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). Retourne nil chez EOF.

fh:read (n)

Lit jusqu'à des n octets. Retourne nil chez EOF.

fh : fermer ()

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

Utilitaires binaires

sbomgen.hash (données, algorithme)

Renvoie le résumé codé en hexadécimal d'une chaîne d'octets en mémoire selon l'algorithme donné. Associez-le sbomgen.read_file(path) pour hacher un fichier que vous avez déjà lu à des fins d'analyse. Il est préférable de le faire sbomgen.hash_file(path) lorsque vous avez besoin à la fois des octets et du résumé, car hash il ne lit pas le fichier à nouveau.

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 (chemin, algorithme)

Renvoie le résumé codé en hexadécimal du contenu d'un fichier selon l'algorithme donné. Achemine la lecture à travers la I/O couche d'artefacts, afin qu'elle fonctionne de manière uniforme sur les artefacts de répertoire, de conteneur, d'archive, de volume et d'hôte local. Utilisez-le lorsque le résumé est la seule chose dont vous avez besoin dans le fichier.

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

Équivalent à sbomgen.hash_file(path, "SHA-256").

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

sbomgen.contains_bytes (chemin, modèles)

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

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

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

Les file_version champs product_version et proviennent de la FixedFileInfo structure PE, au format. "major.minor.build.revision" Le string_table champ est une table imbriquée saisie par code local (par exemple, "040904B0" pour l'Unicode anglais américain). Chaque locale 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 (chemin)

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

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

sbomgen.parse_file_version (chemin)

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

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

Insère la découverte d'un paquet dans le SBOM. Disponible uniquement dans les plugins de collection.

Le pkg tableau prend en charge les champs suivants :

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

Hachages de composants

Le hashes champ facultatif sur les résumés d'intégrité des sbomgen.push_package() enregistrements pour un composant. Les entrées sont saisies par nom d'algorithme et sérialisées dans le components[].hashes tableau CycloneDx, conformément au schéma attendu par Amazon Inspector.

Algorithmes pris en charge

Utilisez les constantes ci-dessous pour sbomgen.hash_algorithms que le nom de l'algorithme passé àsbomgen.hash()/sbomgen.hash_file()soit la même chaîne acceptée par push_package({ hashes = ... }) :

Règles de validation

push_package()valide hashes avant d'émettre un résultat. Un package dont les hachages échouent à la validation est supprimé et un avertissement est enregistré. Validation :

Exemple : hachage d'un manifeste et pièce jointe au résumé

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

Lorsque le résumé est la seule chose dont vous avez besoin dans le fichier, préférez sbomgen.hash_file(path, algo) plutôt que de lire le fichier deux fois : il achemine la lecture à travers la I/O couche d'artefacts en un seul passage.

Propriétés de CycloneDx

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

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 :

Plugin-defined les propriétés 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 s'appuie 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.

Règles de dénomination clés

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

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 plug-in (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 des propriétés qui lui sont propres à chaque composant qu'il émet. Ces valeurs proviennent de l'amazon:inspector:sbom_generator:*espace de noms réservé et ne doivent pas être produites par les plugins. Comportement d'exécution observé :

La taxonomie complète des clés réservées est mise à jour dans le guide de l'utilisateur d'Amazon Inspector : Utilisation des espaces de noms CycloneDX avec Amazon Inspector.

Le contenu du SBOM n'est pas assaini

Sbomgenn'inspecte ni ne filtre les données émises par un plugin. Les noms des composants, les versions, les URL URL, les hachages et les valeurs de propriété sont écrits dans le SBOM comme indiqué. Sbomgenne détecte ni ne supprime les secrets, les informations d'identification, les jetons ou autres données sensibles. Si un plugin place une telle valeur dans une découverte, elle apparaît dans le SBOM de sortie et se déplace partout où ce SBOM est publié.

Vous êtes responsable de ce que vos plugins écrivent. Émettez uniquement des données dérivées de l'artefact que vous souhaitez inventorier et traitez le SBOM comme un artefact partageable lorsque vous décidez quoi inclure.

Constantes de propriété

Built-in les constantes de clé de propriété sont disponibles viasbomgen.properties. Chaque constante ci-dessous se résout en une clé dans l'amazon:inspector:sbom_generator:*espace de noms réservé. Ces constantes existent pour que les scanners intégrés de sbomgen émettent des clés de propriété cohérentes. Il ne s'agit pas de points d'extension pour les plugins personnalisés. Les utiliser dans un plug-in personnalisé permet d'écrire dans un espace de noms réservé, qui peut masquer les valeurs sur lesquelles s'appuie Inspector. Voir Espaces de noms réservés ci-dessus.

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

Groupes de scanners

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

Exemple :

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

Constantes de type de composant

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

Exemple :

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

Constantes d'algorithme de hachage

Constantes pour le paramètre d'algorithme de sbomgen.hash()sbomgen.hash_file(),, et le hashes champ desbomgen.push_package(). Les valeurs de chaîne correspondent aux noms de l'algorithme de hachage CycloneDX, de sorte que la même constante circule sur l'ensemble du chemin de hachage sans traduction.

Exemple :

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

Constantes de plateforme

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

Exemple :

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

Informations sur l'artefact

sbomgen.get_platform ()

Renvoie la chaîne de la plate-forme 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 tableau 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:") provenant de l'environnement de l'artefact. Lit la variable d'SystemDriveenvironnement, avec la valeur par défaut "C:" si elle n'est pas définie. Il s'agit de l'équivalent Lua de. strutils.GetSystemDriverLetter()

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

sbomgen.resolve_glob_paths (modèles)

Étend les modèles globaux du système de fichiers par rapport au système de fichiers hôte. Localhost-only: renvoie nil plus une erreur sur les autres types d'artefacts.

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

Comportement :

Cross-platform séparateurs de chemins :

sbomgen.get_home_dirs ()

Renvoie les racines du répertoire personnel de l'utilisateur pour l'artefact, sous forme de tableau de chemins. Localhost énumère le véritable système de fichiers hôte ; les artefacts de conteneur et de volume énumèrent leur propre système de fichiers (rootfs ou monté) ; tous les autres types d'artefacts renvoient une table vide. Les chemins sont normalisés par une barre oblique, dédupliqués et triés.

Il s'agit d'une méthode prenant en compte les artefacts pour localiser les répertoires par utilisateur (tels que les caches de modèles ou la configuration des outils) sans coder en dur ou. /home/* /Users/* Il inclut le répertoire personnel de root et ignore les répertoires non-utilisateurs connus (profils intégrés tels que Public et Default on WindowsmacOS, Shared on et lost+found onLinux).

function get_localhost_scan_paths()
    local patterns = {}
    for _, home in ipairs(sbomgen.get_home_dirs()) do
        table.insert(patterns, home .. "/.cache/huggingface/hub")
    end
    return sbomgen.resolve_glob_paths(patterns)
end

La composition ci-dessus est réservée à l'hôte local, en raison des resolve_glob_paths erreurs sur les artefacts non locaux. Pour les scans de conteneurs et de volumes, faites plutôt correspondre les racines d'origine renvoyées à la liste de fichiers de l'artefact (par exemple, avecsbomgen.find_files_by_path_regex).

Comportement :

Informations sur le système

Ces fonctions renvoient des métadonnées concernant le système d'exploitation et le 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 les métadonnées du système d'exploitation).

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 quantificateurs ({n,}) et l'anticipation. 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 (étoile, modèle)

Renvoie la première correspondance d'un modèle regex Go, ou nil s'il n'y a pas de correspondance.

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

sbomgen.regex_match (étoile, modèle)

Renvoie les groupes de capture du premier match. L'indice 1 correspond à la correspondance complète, 2 ou 2 sont des groupes de capture.

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

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

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

sbomgen.regex_replace (chaîne, modèle, remplacement)

Remplace toutes les allumettes. La chaîne de remplacement peut utiliser$1,$2, etc. pour les références de groupe de capture.

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

Quand utiliser les modèles Regex par rapport aux modèles Lua

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

Analyse syntaxique structurée

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

sbomgen.json_decode (str)

Analyse une chaîne JSON dans une table Lua.

local doc, err = sbomgen.json_decode('{"name":"requests","version":"2.28.1"}')
if err then return end
sbomgen.log_info(doc.name)

sbomgen.xml_decode (str)

Analyse une chaîne XML dans une table Lua.

Les valeurs XML utilisent la forme suivante :

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 non Windows, registry_open_key renvoie une erreur. L'accèdeur de registre est initialisé paresseusement lors de la première utilisation et prend en charge à la fois l'accès à l'API Windows en direct (analyses de l'hôte local sous Windows) et l'analyse syntaxique des ruches REGF basée sur des fichiers (analyses). container/volume

sbomgen.registry_open_key (chemin)

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

local key, err = sbomgen.registry_open_key("SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\7-Zip")
if err then return end
-- use key...
sbomgen.registry_close(key)

sbomgen.registry_get_string (clé, nom_valeur)

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

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

sbomgen.registry_get_integer (clé, nom_valeur)

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

sbomgen.registry_get_strings (clé, nom_valeur)

Lit une valeur multichaîne (REG_MULTI_SZ) à partir d'une clé de registre ouverte. Renvoie un tableau de chaînes.

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

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

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

Ferme un descripteur de clé de registre. Les poignées de touches 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é par 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_debugn'imprime que lorsque sbomgen est invoqué avec. --verbose

À 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. En cas message d'omission, imprime un message par défaut.

Utilisez-le comme un simple débogueur en plaçant des points d'arrêt à des points clés de votre plugin et en 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 de la testing table globale 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 d'analyse crée un artefact du type donné, exécute le pipeline de découverte → collecte du plugin actuel sur celui-ci et renvoie les résultats qui en résultent. L'pathargument est résolu par rapport au répertoire du fichier de test.

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

Forme du résultat

Chaque table de recherche ne projette que les champs répertoriés ci-dessous. En particulier, namespace et 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

Flux de contrôle

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 des appareils sont _testdata/ placées à côté du fichier de test ; le coureur n'y descend pas _testdata/ lorsqu'il recherche des fichiers de test.

Gestion des erreurs

Les fonctions d'API qui peuvent échouer renvoient deux valeurs :value, err. Le succès, err c'estnil. En cas d'échec, la première valeur est nil et err est 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 plug-in suivant. Les autres plugins ne sont pas concernés.