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 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 (fichier I/O, 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 :

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 des modules autorisés de la machine virtuelle et ne sont pas accessibles aux plugins.

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

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 fichier sont acheminées via 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é.

Limite d'accès aux fichiers

Les fonctions de sbomgen.* fichier limitent les lectures à l'artefact en inventaire. Un chemin résolu en dehors de la racine de l'artefact, par exemple via une ../ 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 régit les lectures de fichiers uniquement. Cela ne limite pas ce qu'un plugin écrit dans le SBOM — voir. Le contenu du SBOM n'est pas désinfecté

sbomgen.get_file_list ()

Renvoie tous les chemins de fichiers de l'artefact sous forme de table 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 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.

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 des modèles 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 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.

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

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 (normalisé par barre oblique) se termine par l'un des suffixes indiqué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 réguliers Go (RE2) donnés. La correspondance s'effectue en dehors de la machine virtuelle Lua, ce qui la rend efficace sur les grandes listes de fichiers.

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

Performances : find_files_by_* ou 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 (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 relatives à 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 d'entrée)

Lit une seule entrée depuis 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 fichier ELF, PE ou Mach-O binaire et recherche dans la constant/variable section par défaut une correspondance regex Go.

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

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

fh:read (n)

Lit jusqu'à 8 n octets. Retours 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 condensé 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, ce qui est préférable sbomgen.hash_file(path) lorsque vous avez besoin à la fois des octets et du résumé, car il hash ne permet pas de relire le fichier.

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, de sorte qu'elle fonctionne de manière uniforme entre les artefacts de répertoire, de conteneur, d'archive, de volume et de localhost. 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 une table de booléens dans le même ordre que les modèles d'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 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.

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 paramètre régional 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 équivalent à 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)

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.

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)

Envoie une recherche de package 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 le hachage échoue à la validation est supprimé et un avertissement est enregistré. Validation :

Exemple : hachage d'un manifeste et ajout du condensé

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 le seul élément 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 clé-valeur associées à un composant dans le 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 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 :

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é :

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

Le contenu du SBOM n'est pas désinfecté

Sbomgenn'inspecte ni ne filtre les données émises par un plugin. Les noms des composants, les versions, les PURL, les hachages et les valeurs de propriété sont écrits dans la 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 recherche, elle apparaît dans la SBOM de sortie et est transmise partout où cette SBOM est publiée.

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 de ce que vous souhaitez inclure.

Constantes de propriété

Built-in les constantes de clé de propriété sont disponibles viasbomgen.properties. Chaque constante ci-dessous se traduit par 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.

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 :

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 :

Exemple :

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

Constantes de l'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 des chaînes correspondent aux noms des algorithmes 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 plate-forme

Constantes de comparaison avecsbomgen.get_platform(). Disponible via sbomgen.platform :

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_artefact_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, la valeur par défaut étant "C:" définie. C'est 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 :

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

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

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

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

sbomgen.regex_match (str, modèle)

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.

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

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.

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 :

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.

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.

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 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 (scans). 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 une table de chaînes de caractères.

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

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

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

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 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 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 plugin suivant. Les autres plugins ne sont pas concernés.