기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

플러그인 API 참조

Inspector-sbomgen Lua 플러그인에 대한 전체 API 참조입니다. 플러그인 작성에 대한 지침은 섹션을 참조하세요플러그인 개발자 안내서. 테스트는 단원을 참조하십시오플러그인 테스트 가이드.

개요

모든 런타임 제공 함수는 글로벌 sbomgen 테이블(파일 I/O, 정규식, 로깅, 상수 등)을 통해 액세스됩니다. 또한 각 플러그인은 플러그인 수명 주기의 정의된 지점에서 sbomgen 호출을 수행하는 작은 최상위 글로벌 함수 세트(discover, collectget_scanner_name, subscribe_to_event, 등)를 정의합니다. 이는에 설명되어 있습니다플러그인 수명 주기 글로벌.

*_test.lua 파일 내에서 sbomgen은 테스트 작성자가 Discovery→컬렉션 파이프라인을 구동하고 어설션할 수 있는 testing 글로벌를 추가로 노출합니다. API 테스트을(를) 참조하세요.

샌드박스 제한 사항

플러그인은 표준 라이브러리 액세스가 제한된 샌드박스 Lua VM에서 실행됩니다. 다음 Lua 표준 라이브러리 모듈을 사용할 수 있습니다.

다음 표준 라이브러리 모듈은 보안 및 안정성을 위해 명시적으로 허용되지 않습니다.

이러한 모듈은 VM의 허용 목록에 없으며 플러그인에서 액세스할 수 없습니다.

플러그인 수명 주기 글로벌

플러그인은 특정 최상위 글로벌 함수를 init.lua 정의하는 라는 Lua 파일입니다. 이러한 전역은 sbomgen 테이블에 없습니다. 플러그인이 sbomgen이 호출하도록 정의하는 함수입니다. 유효한 전역 세트는 검색 플러그인과 컬렉션 플러그인 간에 다릅니다. 아래 모든 함수에 대해 플러그인이 이를 생략하면 표에 표시된 기본값이 사용됩니다.

검색 플러그인

컬렉션 플러그인

파일 I/O

모든 파일 작업은 sbomgen.* API를 거쳐야 합니다. Lua의 io 라이브러리를 통한 직접 파일 시스템 액세스는 사용할 수 없습니다( 참조샌드박스 제한 사항). sbomgen 파일 I/O 함수는 아티팩트 인터페이스를 통해 라우팅되므로 디스크의 디렉터리, 컨테이너 이미지, 압축된 아카이브 또는 마운트된 볼륨을 스캔하든 플러그인이 동일하게 작동합니다.

파일 액세스 경계

sbomgen.* 파일 함수는 인벤토리 아래의 아티팩트에 대한 읽기를 제한합니다. 예를 들어 ../ 순회를 통해 아티팩트 루트 외부에서 확인되는 경로는 거부되고 호출은 호스트 파일 시스템을 읽는 대신 오류를 반환합니다. 이는 read_file, open_file, file_stat, read_dir및 경로를 취하는 바이너리/해시 헬퍼에 적용됩니다.

호스트 자체의 인벤토리를 생성하는 localhost 아티팩트 유형은 예외입니다. 호스트 파일 시스템은 아티팩트이므로 읽기는 더 좁은 루트로 제한되지 않습니다.

이 경계는 파일 읽기만 관리합니다. 플러그인이 SBOM에 쓰는 내용을 제한하지 않습니다. 단원을 참조하십시오SBOM 콘텐츠가 삭제되지 않음.

sbomgen.get_file_list()

아티팩트의 모든 파일 경로를 문자열 테이블로 반환합니다.

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

파일의 전체 내용을 읽고 문자열로 반환합니다.

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

sbomgen.open_file(path)

읽기 스트리밍을 위한 파일을 엽니다. FileHandle 객체를 반환합니다. 전체 콘텐츠를 메모리로 로드하는 것이 실용적이지 않은 대용량 파일에 사용합니다.

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)

Go filepath.Match glob 패턴과 일치하는 파일을 반환합니다. 패턴은 기본 파일 이름과 일치합니다. Symlink는 건너뛰고 구체적인 파일만 반환됩니다.

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

전체 경로 패턴 일치string.match를 위해와 sbomgen.get_file_list() 함께를 사용합니다.

sbomgen.find_files_by_name(names)

기본 이름(마지막 경로 구성 요소)이 지정된 이름 중 하나와 정확히 일치하는 파일을 반환합니다. 반복 및 비교는 Go에서 수행되므로 Luasbomgen.get_file_list()에서 반복하는 것보다 훨씬 빠릅니다.

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)

기본 이름이 지정된 이름 중 하나와 일치하고 대/소문자를 무시하는 파일을 반환합니다. 예를 들어는 VERSION, 및 Version와 "version" 일치합니다version. 와 마찬가지로 find_files_by_name일치는 Lua VM 외부에서 발생합니다.

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)

전체(forward-slash-normalized) 경로가 지정된 접미사 중 하나로 끝나는 파일을 반환합니다. 와 마찬가지로 find_files_by_name일치는 Lua VM 외부에서 발생합니다.

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)

forward-slash-normalized 경로가 지정된 Go(RE2) 정규식 패턴과 일치하는 파일을 반환합니다. 일치는 Lua VM 외부에서 발생하므로 대용량 파일 목록에서 효율적입니다.

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

성능: find_files_by_* vs get_file_list

검색 플러그인의 경우 Luaget_file_list()에서 find_files_by_namefind_files_by_suffix, 또는를 반복하는 find_files_by_path_regex 것보다 선호합니다. 300K 파일을 사용한 localhost 스캔에서를 사용하여 Lua에서 파일 목록을 반복하는 데 약 15초가 string.match() 걸리고는 1밀리초 이내에 find_files_by_name 완료됩니다. 차이점은가 모든 파일 경로를 Lua VM에 문자열로 get_file_list() 복사한 다음 Lua가 각 파일마다 루프와 패턴 일치를 해석한다는 것입니다. find_files_by_* 함수는 Lua VM 외부에서 일치하는를 수행하고 일치하는 경로만 반환하므로 복사 및 경로별 해석 오버헤드가 모두 발생하지 않습니다.

기본 이름, 접미사 또는 정규식 일치로 표현할 수 없는 사용자 지정 일치 로직이 필요한 get_file_list() 경우에만를 사용합니다.

sbomgen.read_dir(path)

디렉터리의 항목을 나열합니다.

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)

파일에 대한 메타데이터를 반환합니다.

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)

ZIP, JAR 또는 WAR 아카이브에서 단일 항목을 읽습니다.

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

sbomgen.search_binary(path, regex)

파일을 ELF, PE 또는 Mach-O 바이너리로 구문 분석하고 기본 상수/변수 섹션에서 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(path, regex [, n])

파일을 ELF, PE 또는 Mach-O 바이너리로 구문 분석하고 기본 상수/변수 섹션에서 모든 고유한 첫 번째 캡처 그룹 일치를 반환합니다. 를 전달n하여 결과를 제한합니다.

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)

전체 이진 파일에서 특정 섹션에 국한되지 않는 첫 번째 정규식 일치를 검색합니다. 예를 들어 버전 문자열이 비표준 섹션에 있는 경우와 같이 섹션 기반 검색(search_binary)이 충분하지 않은 경우를 사용합니다.

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

FileHandle 메서드

FileHandle 객체는에서 반환됩니다sbomgen.open_file().

fh:read_line()

다음 줄을 읽습니다(새 줄 문자 제외). EOFnil에서를 반환합니다.

fh:read(n)

최대 n바이트를 읽습니다. EOFnil에서를 반환합니다.

fh:close()

파일 핸들을 닫습니다. 완료되면 항상 핸들을 닫습니다.

바이너리 유틸리티

sbomgen.hash(data, algorithm)

지정된 알고리즘에서 인 메모리 바이트 문자열의 16진수 인코딩 다이제스트를 반환합니다. 와 페어링sbomgen.read_file(path)하여 구문 분석을 위해 이미 읽은 파일을 해시합니다. hash는 파일을 다시 읽지 않으므로 바이트와 다이제스트가 모두 필요한 sbomgen.hash_file(path) 경우보다 선호됩니다.

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(path, algorithm)

지정된 알고리즘에 따라 파일 콘텐츠의 16진수 인코딩 다이제스트를 반환합니다. 읽기를 아티팩트 I/O 계층을 통해 라우팅하므로 디렉터리, 컨테이너, 아카이브, 볼륨 및 로컬 호스트 아티팩트에서 균일하게 작동합니다. 다이제스트가 파일에서 필요한 유일한 사물인 경우이 옵션을 사용합니다.

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

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(path, patterns)

파일에 지정된 각 바이트 패턴이 포함되어 있는지 확인합니다. 입력 패턴과 동일한 순서로 부울 테이블을 반환합니다.

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)

바이너리 파일의 Windows PE 버전 리소스를 구문 분석합니다. 파일에서 PE 바이너리가 아니거나 버전 리소스가 없는 nil, err 경우 버전 필드가 있는 테이블을 반환합니다.

product_version 및 file_version 필드는 형식의 PE FixedFileInfo 구조에서 가져옵니다"major.minor.build.revision". string_table 필드는 로캘 코드로 입력되는 중첩 테이블입니다(예: 미국 영어 유니코드의 "040904B0" 경우 ). 각 로캘은 PEStringFileInfo(ProductVersion, ProductNameFileDescription, 등)에서 가져온 이름/값 페어 테이블에 매핑됩니다. PE 바이너리는 하나 이상의 로캘을 노출할 수 있습니다.

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)

PE 바이너리의 FixedFileInfo에서 제품 버전 문자열만 반환하는 편의 래퍼입니다. 호출 get_pe_version_info(path) 및 읽기와 동일합니다product_version.

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

sbomgen.parse_file_version(path)

PE 바이너리의 FixedFileInfo에서 파일 버전 문자열만 반환하는 편리한 래퍼입니다. 호출 get_pe_version_info(path) 및 읽기와 동일합니다file_version.

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

패키지 출력

sbomgen.push_package(pkg)

패키지 결과를 SBOM으로 푸시합니다. 컬렉션 플러그인에서만 사용할 수 있습니다.

이 pkg 테이블은 다음 필드를 지원합니다.

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

구성 요소 해시

의 선택적 hashes 필드는 구성 요소에 대한 무결성 다이제스트를 sbomgen.push_package() 기록합니다. 항목은 알고리즘 이름으로 입력되고 Amazon Inspector에서 기대하는 스키마와 일치하는 CycloneDX components[].hashes 배열로 직렬화됩니다.

지원되는 알고리즘

/에 전달된 알고리즘 이름이 sbomgen.hash()에서 수락한 것과 동일한 문자열sbomgen.hash_file()이 sbomgen.hash_algorithms 되도록 아래의 상수를 사용합니다push_package({ hashes = ... }).

검증 규칙

push_package()는 결과를 보내기 hashes 전에 검증합니다. 해시 검증에 실패한 패키지가 삭제되고 경고가 기록됩니다. 검증:

예: 매니페스트 해싱 및 다이제스트 연결

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

다이제스트가 파일에서 필요한 유일한 사물인 경우 파일을 두 번 읽는 sbomgen.hash_file(path, algo) 것보다 선호합니다. 그러면 읽기가 아티팩트 I/O 계층을 통해 단일 패스로 라우팅됩니다.

CycloneDX 속성

CycloneDX 속성은 SBOM의 구성 요소에 연결된 키-값 메타데이터입니다. PURL 한정자와 구별됩니다.

예약 네임스페이스

CycloneDX 속성 네임스페이스 amazon:inspector:* 패밀리는 Amazon Inspector용으로 예약되어 있습니다.

플러그인 정의 속성은 이러한 네임스페이스를 사용해서는 안 됩니다. 예약된 네임스페이스에 쓰면 Inspector가 의존하는 값과 섀도우가 되거나 충돌할 수 있으며, 취약성 식별 중에 결과 SBOM이 잘못 해석될 수 있습니다. 예약 키의 전체 목록은 Amazon Inspector에서 CycloneDX 네임스페이스 사용을 참조하세요.

키 이름 지정 규칙

에 전달된 속성 키sbomgen.push_package()는 다음과 같이 처리됩니다.

정의한 속성 키에 항상 콜론을 하나 이상 포함합니다. 조직 또는 플러그인에 고유한 네임스페이스를 사용합니다(예: acme:python-pip:*).

properties = {
    -- Custom namespace — safe to use (recommended)
    ["acme:python-pip:manifest_path"] = file_path,
    ["acme:python-pip:pinned"]        = "true",

    -- Fully-qualified key outside amazon:inspector:* — also fine
    ["my:custom:namespace:key"] = "value",

    -- No colon: avoid — ends up as "amazon:inspector:sbom_generator:custom_field"
    -- custom_field = "value",
}

sbomgen에서 설정한 속성

Sbomgen은 자체 속성을 내보내는 모든 구성 요소에 연결할 수 있습니다. 이러한 값은 예약된 amazon:inspector:sbom_generator:* 네임스페이스에서 가져온 것이므로 플러그인에서 생성해서는 안 됩니다. 관찰된 런타임 동작:

예약 키의 전체 분류는 Amazon Inspector 사용 설명서: Amazon Inspector에서 CycloneDX 네임스페이스 사용에서 관리됩니다.

SBOM 콘텐츠가 삭제되지 않음

Sbomgen는 플러그인이 내보내는 데이터를 검사하거나 필터링하지 않습니다. 구성 요소 이름, 버전, PURLs, 해시 및 속성 값은 제공된 대로 SBOM에 기록됩니다. Sbomgen는 보안 암호, 자격 증명, 토큰 또는 기타 민감한 데이터를 감지하거나 수정하지 않습니다. 플러그인이 이러한 값을 결과에 배치하면 출력 SBOM에 나타나고 SBOM이 게시되는 모든 곳으로 이동합니다.

플러그인이 작성하는 내용에 대한 책임은 사용자에게 있습니다. 인벤토리를 작성하려는 아티팩트에서 파생된 데이터만 내보내고, 포함할 항목을 결정할 때 SBOM을 공유 가능한 아티팩트로 취급합니다.

속성 상수

기본 제공 속성 키 상수는를 통해 사용할 수 있습니다sbomgen.properties. 아래의 모든 상수는 예약된 amazon:inspector:sbom_generator:* 네임스페이스 내의 키로 확인됩니다. 이러한 상수는 sbomgen의 내장 스캐너가 일관된 속성 키를 방출하도록 존재합니다. 사용자 지정 플러그인의 확장 지점이 아닙니다. 사용자 지정 플러그인에서 이를 사용하면 Inspector가 의존하는 값을 섀도우할 수 있는 예약된 네임스페이스에 씁니다. 위의 섹션을 참조예약 네임스페이스하세요.

사용자 지정 플러그인 작성자는 이러한 상수를 재사용하는 대신 자체 네임스페이스(예: acme:my_plugin:*)에서 속성을 정의해야 합니다.

스캐너 그룹

검색 플러그인은를 통해 스캐너 그룹을 선언해야 합니다get_scanner_groups(). 그룹은 스캐너를 분류하고 사용자가 범주를 선택적으로 활성화하거나 비활성화할 수 있도록 허용합니다. 상수는를 통해 사용할 수 있습니다sbomgen.groups.

예제:

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

구성 요소 유형 상수

의 component_type 필드는 CycloneDX 1.5 구성 요소 유형 중 하나여야 push_package() 합니다. 상수는를 통해 사용할 수 있습니다sbomgen.component_types.

예제:

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

해시 알고리즘 상수

sbomgen.hash(), 및 hashes 필드의 알고리즘 파라미터sbomgen.hash_file()에 대한 상수입니다sbomgen.push_package(). 문자열 값은 CycloneDX 해시 알고리즘 이름과 일치하므로 동일한 상수가 변환 없이 전체 해싱 경로를 통과합니다.

예제:

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

플랫폼 상수

와 비교하기 위한 상수입니다sbomgen.get_platform(). 를 통해 사용 가능sbomgen.platform:

예제:

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

아티팩트 정보

sbomgen.get_platform()

런타임 플랫폼 문자열(예: , "linux""windows", "darwin")을 반환합니다.

sbomgen.get_artifact_type()

스캔 중인 아티팩트 유형(예: , "directory""archive")을 반환합니다.

sbomgen.should_collect_licenses()

사용자가를 통해 라이선스 컬렉션을 활성화한 true 경우를 반환합니다--collect-licenses.

sbomgen.get_env_vars()

아티팩트의 환경 변수를 {key, value} 항목 테이블로 반환합니다.

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

아티팩트 환경에서 시스템 드라이브 문자(예: "C:")를 반환합니다. SystemDrive 환경 변수를 읽으며 설정되지 않은 "C:" 경우 기본값은 입니다. 이는와 동등한 Lua입니다strutils.GetSystemDriverLetter().

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

sbomgen.resolve_glob_paths(patterns)

호스트 파일 시스템에 대해 파일 시스템 glob 패턴을 확장합니다. Localhost 전용:에서 다른 아티팩트 유형에 대한 오류를 nil 반환합니다.

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

동작:

교차 플랫폼 경로 구분자:

시스템 정보

이러한 함수는 아티팩트의 운영 체제 및 하드웨어에 대한 메타데이터를 반환합니다. 정보를 사용할 수 없는 경우(예: OS 메타데이터 없이 디렉터리를 스캔하는 경우) 값은 빈 문자열일 수 있습니다.

정규 표현식

Lua의 기본 제공 패턴에는 변경(|), 한정자 범위({n,}) 및 미리 보기와 같은 기능이 없습니다. 이 격차를 해소하기 위해 sbomgen은 Go의 regexp 패키지를 직접 노출합니다. 이러한 함수는 Lua 패턴이 아닌 Go 정규식 구문(RE2)을 사용합니다.

sbomgen.regex_find(str, pattern)

Go 정규식 패턴의 첫 번째 일치 항목을 반환하거나 일치하지 않는 nil 경우 반환합니다.

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

sbomgen.regex_match(str, pattern)

첫 번째 매치에서 캡처 그룹을 반환합니다. 인덱스 1은 전체 일치 항목이고, 2+는 캡처 그룹입니다.

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

겹치지 않는 모든 일치 항목을 반환합니다. 를 전달n하여 결과를 제한합니다(기본값: 모두).

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

sbomgen.regex_replace(str, pattern, replacement)

모든 일치 항목을 대체합니다. 대체 문자열은 캡처 그룹 참조에 $1$2, 등을 사용할 수 있습니다.

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

정규식과 Lua 패턴을 사용해야 하는 경우

간단한 패턴에는 Lua의 내장 string.match/string.find를 사용합니다. 더 빠르고 백슬래시 이스케이프가 필요하지 않습니다. 필요한 sbomgen.regex_* 경우를 사용합니다.

구조화된 구문 분석

Sbomgen은 구조화된 텍스트 형식을 Lua 테이블로 직접 디코딩하기 위한 경량 헬퍼를 노출합니다.

sbomgen.json_decode(str)

JSON 문자열을 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)

XML 문자열을 Lua 테이블로 구문 분석합니다.

XML 값은 다음 셰이프를 사용합니다.

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)

Windows 레지스트리

이러한 함수는 Windows 레지스트리에 대한 읽기 전용 액세스를 제공합니다. Windows가 아닌 아티팩트에서는 오류를 registry_open_key 반환합니다. 레지스트리 액세스 도구는 처음 사용할 때 느리게 초기화되며 라이브 Windows API 액세스(Windows의 로컬 호스트 스캔)와 파일 기반 REGF hive 구문 분석(컨테이너/볼륨 스캔)을 모두 지원합니다.

sbomgen.registry_open_key(path)

레지스트리 키를 엽니다. 로 닫아야 하는 키 핸들을 반환합니다registry_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(key, value_name)

열린 레지스트리 키에서 문자열 값을 읽습니다.

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

sbomgen.registry_get_integer(key, value_name)

열린 레지스트리 키에서 정수 값을 읽습니다.

sbomgen.registry_get_strings(key, value_name)

열린 레지스트리 키에서 다중 문자열(REG_MULTI_SZ) 값을 읽습니다. 문자열 테이블을 반환합니다.

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)

열려 있는 레지스트리 키 아래에 있는 모든 하위 키 이름을 반환합니다.

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)

레지스트리 키 핸들을 닫습니다. 키 핸들도 가비지 수집기에 의해 자동으로 닫히지만 명시적으로 닫는 것이 좋습니다.

로깅

로그 메시지는 sbomgen의 콘솔 출력에 기록됩니다. 플러그인에서 내보내는 모든 메시지에는 플러그인의 소스 레이블 및 에코시스템 접두사가 자동으로 붙습니다. 예를 들면 다음과 같습니다.

[custom:python-pip] Parsing requirements.txt

log_info, log_warn및는 log_error 항상 인쇄됩니다.는 sbomgen이 로 호출될 때log_debug만 인쇄됩니다--verbose.

형식이 지정된 메시지string.format에를 사용합니다.

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

함수 디버깅

sbomgen.breakpoint(message)

사용자가 Enter 키를 누message를 때까지 stderr로 인쇄하고 실행을 차단합니다. message이 생략되면가 기본 메시지를 인쇄합니다.

플러그인의 키 포인트에 중단점을 배치하고 로 실행하여 주변 로그 출력을 --verbose 확인하여 이를 미정 디버거로 사용합니다.

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

API 테스트

글로벌 testing 테이블 아래의 함수는에서 로드한 플러그인 테스트 파일(*_test.lua)에서만 사용할 수 있습니다inspector-sbomgen plugin test. 런타임에는 검색 또는 컬렉션 플러그인에서 사용할 수 없습니다. 전체 sbomgen.* API는 테스트 파일 내에서도 사용할 수 있지만 아티팩트(예: sbomgen.read_file())가 필요한 sbomgen.* 함수는 스캔 내에서 호출될 때만 의미 있는 결과를 생성합니다. 서술 가이드는 단원을 참조하십시오플러그인 테스트 가이드.

스캔 함수

각 스캔 함수는 지정된 종류의 아티팩트를 생성하고, 해당 아티팩트에 대해 현재 플러그인의 검색 → 수집 파이프라인을 실행하고, 결과 결과를 반환합니다. path 인수는 테스트 파일의 디렉터리를 기준으로 확인됩니다.

6개 모두 아래 셰이프의 결과 테이블을 반환합니다.

결과 셰이프

각 조사 결과 테이블은 아래 나열된 필드만 프로젝션합니다. 특히 namespace 및 purl_type는 별도로 프로젝션되지 않으며 전체 purl 문자열에 통합됩니다.

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)

어설션

제어 흐름

테스트 검색

파일 일치test_에서 이름이 로 시작하는 모든 글로벌 Lua 함수*_test.lua는 테스트로 처리됩니다. 테스트 파일은 정상 {phase}/{platform}/{category}/{ecosystem}/ 깊이init.lua에서 옆에 있어야 합니다. 수정 데이터는 테스트 파일 _testdata/ 옆에 들어갑니다. 러너는 테스트 파일을 검색할 _testdata/ 때 로 내림차순되지 않습니다.

오류 처리

실패할 수 있는 API 함수는 라는 두 값을 반환합니다value, err. 성공 시 err는 입니다nil. 실패 시 첫 번째 값은 nil 이고 err는 오류 문자열입니다.

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

플러그인에서 처리되지 않은 Lua 오류가 발생하면 sbomgen은 경고를 기록하고 다음 파일 또는 플러그인을 계속 진행합니다. 다른 플러그인은 영향을 받지 않습니다.