플러그인 API 참조

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

개요

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

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

샌드박스 제한 사항

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

모듈	참고
base	코어 함수(print, type, tostring, tonumber, pairs, ipairs, pcall, error, select, unpackrawgetrawset, 등). dofile, 및 loadfile는 제거loadstring됩니다.
string	전체 문자열 조작(string.match, string.find, string.formatstring.gsub, 등)
table	전체 테이블 조작(table.insert, table.remove, table.sorttable.concat, 등)
math	전체 수학 라이브러리(math.floor, math.maxmath.min, 등)
package	require()는 사용할 수 있지만 플러그인의 자체 디렉터리 트리 내의 모듈로 제한됩니다. 상위 디렉터리 순회(require("../shared"))가 차단됩니다. package.cpath 및 package.path가 지워집니다.

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

모듈	이유
io	직접 파일 시스템 액세스가 차단됩니다. 모든 파일 작업은 아티팩트 유형(디렉터리, 컨테이너, 볼륨 등)에서 일관된 동작을 위해 아티팩트 인터페이스를 통해 라우팅되는 sbomgen.* 함수를 거쳐야 합니다.
os	플러그인이 호스트 시스템을 수정하지 못하도록 시스템 수준 작업(os.execute, os.removeos.rename, os.getenv, 등)이 차단됩니다.
debug	Lua VM 내부 검사 또는 수정을 방지하기 위해 디버그 라이브러리가 차단됩니다.
coroutine	코루틴은 로드되지 않습니다.

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

참고

중요: 모든 파일 I/O는 sbomgen.* 함수(예: , sbomgen.read_filesbomgen.open_file, sbomgen.get_file_list)를 거쳐야 합니다. io.open 또는 직접 파일 시스템 액세스를 사용하면 런타임 오류가 발생합니다. sbomgen API는 플러그인이 아티팩트 추상화 계층과 상호 작용하도록 하여 디렉터리, 컨테이너 이미지, 아카이브 또는 볼륨을 스캔하든 일관된 동작을 제공합니다.

플러그인 수명 주기 글로벌

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

검색 플러그인

함수	아리티	필수	기본값(생략된 경우)	설명
discover()	0	예	—	이 플러그인이 찾은 파일을 반환합니다. 경로 문자열의 순차적 테이블(단일 이벤트 모드) 또는 값이 경로 테이블(다중 이벤트 모드)인 이벤트 이름 문자열로 키가 지정된 테이블을 반환합니다.
get_event_name()	0	아니요	"lua:{platform}/{category}/{ecosystem}"	파일이 게시되는 이벤트 이름을 반환합니다. 모든 검색 플러그인에서 고유해야 합니다.
get_scanner_name()	0	아니요	에코시스템 디렉터리 이름	스캐너의 표시 이름을 반환합니다. 모든 검색 플러그인에서 고유해야 합니다.
get_scanner_description()	0	아니요	"Lua discovery plugin: {ecosystem}"	사람이 읽을 수 있는 설명을 반환합니다.
get_scanner_groups()	0	아니요	범주 디렉터리에서 파생됨(개발자 가이드 참조)	스캐너 그룹 문자열 테이블을 반환합니다. sbomgen.groups.* 상수를 사용합니다.
get_localhost_scan_paths()	0	아니요	—	로컬 호스트 아티팩트를 스캔할 때 포함할 파일/디렉터리 경로 테이블을 반환합니다. localhost 스캔에만 참조됩니다.

컬렉션 플러그인

함수	아리티	필수	기본값(생략된 경우)	설명
collect(file_path)	1	예	—	구독된 이벤트에 게시된 파일당 한 번 호출됩니다. 파일을 구문 분석하고를 통해 결과를 내보냅니다sbomgen.push_package(). 아무것도 반환하지 않습니다.
subscribe_to_event()	0	아니요	"lua:{platform}/{category}/{ecosystem}"	이 수집기가 구독하는 이벤트 이름을 반환합니다. 해당 검색 플러그인의와 일치해야 합니다get_event_name().
get_collector_name()	0	아니요	에코시스템 디렉터리 이름	수집기의 표시 이름을 반환합니다. 모든 컬렉션 플러그인에서 고유해야 합니다.
get_collector_description()	0	아니요	"" (비어 있음)	사람이 읽을 수 있는 설명을 반환합니다.

파일 I/O

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

sbomgen.get_file_list()

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

• 반환: {string, ...}- 절대 파일 경로 문자열 테이블

• 성능:이 함수는 아티팩트의 모든 파일 경로를 Lua VM에 Lua 문자열로 복사합니다. 대용량 아티팩트(예: 300K 개 이상의 파일을 사용한 localhost 스캔)의 경우이 작업에만 몇 초가 걸립니다. Lua에서 반환된 테이블을 로 반복하면 오버헤드string.match()가 추가됩니다. 전체 스캔에는 15초 이상이 걸릴 수 있습니다. 아티팩트에 파일이 많을수록 플러그인 속도가 느려집니다.

참고

가능하면 다음과 같은 대상 대안을 선호합니다.

함수	다음과 같은 경우에 사용합니다.
sbomgen.find_files_by_name()	일치시킬 정확한 파일 이름(예: , )을 알고 있습니다. "requirements.txt" "curl"
sbomgen.find_files_by_name_icase()	위와 동일하지만 대소문자를 구분하지 않음
sbomgen.find_files_by_suffix()	경로 접미사(예: , "/pom.properties""curlver.h")와 일치해야 합니다.
sbomgen.find_files_by_path_regex()	전체 경로 정규식 일치가 필요합니다.
sbomgen.glob_find_files()	glob 스타일 기본 이름 일치가 필요합니다.

이러한 함수는 Lua VM 외부에서 매칭을 수행하고 매칭된 경로만 반환하여 300K-file 아티팩트에서도 1밀리초 이내에 완료됩니다. 일치하는 로직을 위의 항목 중 하나로 표현할 수 없는 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)

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

• 다음을 반환합니다. string, err

• 실패 시: 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)

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

• 다음을 반환합니다. 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)

Go filepath.Match glob 패턴과 일치하는 파일을 반환합니다. 패턴은 기본 파일 이름과 일치합니다.

• 다음을 반환합니다. {string, ...}, err

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()에서 반복하는 것보다 훨씬 빠릅니다.

• 파라미터: names - 문자열 테이블(일치할 기본 이름)

• 반환: {string, ...}- 일치하는 파일 경로(오류 튜플 없음)

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 외부에서 발생합니다.

• 파라미터: names - 문자열 테이블(일치할 기본 이름, 대/소문자를 구분하지 않음)

• 반환: {string, ...}- 일치하는 파일 경로(오류 튜플 없음)

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 외부에서 발생합니다.

• 파라미터: suffixes - 문자열 테이블(일치할 경로 접미사)

• 반환: {string, ...}- 일치하는 파일 경로(오류 튜플 없음)

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 외부에서 발생하므로 대용량 파일 목록에서 효율적입니다.

• 파라미터: patterns- Go 정규식 문자열 테이블

• 반환: {string, ...}- 일치하는 파일 경로(오류 튜플 없음)

• Raises: 패턴이 컴파일되지 않는 경우 Lua 오류 발생

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)

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

• 다음을 반환합니다. {{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)

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

• 다음을 반환합니다. {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)

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

• 다음을 반환합니다. string, err

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 정규식 일치를 검색합니다.

• 반환: string|nil, err- 일치하는 문자열 또는 일치하지 않는 경우 nil을 반환합니다.

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하여 결과를 제한합니다.

• 반환: {string, ...}|nil, err- 일치하는 문자열 테이블 또는 일치하는 문자열이 없는 경우 nil

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)이 충분하지 않은 경우를 사용합니다.

• 반환: - 일치하는 문자열 또는 일치하지 않는 경우 nil을 반환합니다. string|nil, err

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

FileHandle 메서드

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

fh:read_line()

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

• 다음을 반환합니다. string|nil, err

fh:read(n)

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

• 다음을 반환합니다. string|nil, err

fh:close()

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

바이너리 유틸리티

sbomgen.sha256(path)

파일 콘텐츠의 16진수 인코딩 SHA-256 해시를 반환합니다.

• 다음을 반환합니다. 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)

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

• 다음을 반환합니다. {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)

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

• 다음을 반환합니다. {product_version, file_version, string_table}, 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.

• 다음을 반환합니다. 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)

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

• 다음을 반환합니다. string, err

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 테이블은 다음 필드를 지원합니다.

필드	유형	필수	설명
name	문자열	예	패키지 이름
version	문자열	No	해결된 버전 문자열
namespace	문자열	No	PURL 네임스페이스(예: , "curl""wordpress/plugin")
purl_type	문자열	예	PURL 유형(예: , "pypi", "npm""cargo", "deb", "generic")
component_type	문자열	예	CycloneDX 구성 요소 유형, sbomgen.component_types.* 상수 사용(예: sbomgen.component_types.LIBRARY)
qualifiers	테이블	아니요	키-값 페어로서의 PURL 한정자(패키지 URL에 표시됨)
properties	테이블	아니요	키-값 페어로서의 CycloneDX 구성 요소 속성( 참조CycloneDX 속성)
children	테이블	아니요	중첩된 하위 패키지, 각각 동일한 모양(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",
    },
})

CycloneDX 속성

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

• qualifiers - PURL 한정자입니다. 이는 패키지 URL 문자열(예: pkg:deb/debian/curl@7.88.1?arch=amd64)의 일부가 됩니다. 일부 PURL 한정자는 Amazon Inspector에 의미론적 의미를 부여하고 취약성 식별에 영향을 미칩니다. 패키지 URL이란 무엇입니까?를 참조하세요. - Inspector의 유형별 규칙입니다.

• properties - CycloneDX 구성 요소 속성입니다. 이는 SBOM의 components[].properties 배열에 나타나며 구성 요소의 식별 방법은 변경되지 않습니다.

예약 네임스페이스

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

• amazon:inspector:sbom_generator:* - sbomgen 및 내장 스캐너에서 사용됩니다.

• amazon:inspector:sbom_scanner:* - Amazon Inspector 스캔 API에서 사용됩니다.

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

키 이름 지정 규칙

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

입력 키	SBOM의 결과 키	사용자 지정 플러그인에 권장되나요?
포함:(예: acme:my_plugin:field)	축어적 사용	예 - 모든 플러그인 정의 속성을 자체 네임스페이스에 배치합니다.
아니요:(예: field)	에 자동 접두사 지정 amazon:inspector:sbom_generator:field	아니요 - 예약된 네임스페이스에 씁니다.

정의한 속성 키에 항상 콜론을 하나 이상 포함합니다. 조직 또는 플러그인에 고유한 네임스페이스를 사용합니다(예: 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:* 네임스페이스에서 가져온 것이므로 플러그인에서 생성해서는 안 됩니다. 관찰된 런타임 동작:

• source_path는 항상 sbomgen에 의해 추가됩니다.

• source_file_scanner source_package_collector가 활성화되면 및 --enable-debug-props가 추가됩니다.

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

속성 상수

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

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

상수	해결된 값
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

스캐너 그룹

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

상수	값	설명
sbomgen.groups.OS	"os"	OS 패키지 관리자(dpkg, rpm 등)
sbomgen.groups.PROGRAMMING_LANGUAGE	"programming-language-packages"	언어 패키지 관리자(pip, npm, maven 등)
sbomgen.groups.BINARY	"binary"	컴파일된 바이너리 분석(Go, Rust)
sbomgen.groups.PACKAGE_COLLECTOR	"pkg-scanner"	일반 패키지 컬렉션
sbomgen.groups.EXTRA_ECOSYSTEMS	"extra-ecosystems"	추가 에코시스템(curl, nginx 등)
sbomgen.groups.CERTIFICATE	"certificate"	인증서 스캔
sbomgen.groups.CUSTOM	"custom"	를 통해 로드된 모든 사용자 지정 플러그인에 자동으로 추가됨 --plugin-dir
sbomgen.groups.MACHINE_LEARNING	"machine-learning"	기계 학습 모델 감지

예제:

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

예제:

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

플랫폼 상수

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

상수	값
sbomgen.platform.LINUX	"linux"
sbomgen.platform.WINDOWS	"windows"
sbomgen.platform.DARWIN	"darwin"

예제:

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/"

시스템 정보

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

함수	반환
sbomgen.get_os_name()	OS 이름(예: , "Ubuntu""Alpine Linux")
sbomgen.get_os_version()	OS 버전(예: , "22.04""3.18")
sbomgen.get_os_codename()	OS 코드 이름(예: , "jammy""bookworm")
sbomgen.get_os_id()	OS 식별자(예: , "ubuntu""alpine")
sbomgen.get_kernel_name()	커널 이름(예: "Linux")
sbomgen.get_kernel_version()	커널 버전 문자열
sbomgen.get_cpu_arch()	CPU 아키텍처(예: , "x86_64""aarch64")
sbomgen.get_hostname()	시스템의 호스트 이름

정규 표현식

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

sbomgen.regex_find(str, pattern)

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

• 다음을 반환합니다. string|nil, err

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

sbomgen.regex_match(str, pattern)

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

• 다음을 반환합니다. {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])

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

• 다음을 반환합니다. {string, ...}|nil, err

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

sbomgen.regex_replace(str, pattern, replacement)

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

• 다음을 반환합니다. string, err

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

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

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

• 대체: (foo|bar)

• 양자 범위: \d{8,}

• Lua 패턴으로 표현할 수 없는 복잡한 문자 클래스

구조화된 구문 분석

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

sbomgen.json_decode(str)

JSON 문자열을 Lua 테이블에 구문 분석합니다.

• 다음을 반환합니다. 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)

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

• 다음을 반환합니다. table|nil, err

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

• _name - 요소 이름

• _attr - 속성 테이블, 있는 경우

• _text - 텍스트 콘텐츠가 있는 경우 잘라내기

• 숫자 인덱스 1..n - 하위 요소

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.

• 다음을 반환합니다. 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)

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

• 다음을 반환합니다. string, err

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

sbomgen.registry_get_integer(key, value_name)

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

• 다음을 반환합니다. number, err

sbomgen.registry_get_strings(key, value_name)

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

• 다음을 반환합니다. {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)

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

• 다음을 반환합니다. {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)

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

로깅

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

[custom:python-pip] Parsing requirements.txt

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

함수	수준	기본적으로 표시됩니까?
sbomgen.log_debug(message)	DEBUG	아니요 -에 필요 --verbose
sbomgen.log_info(message)	INFO	예
sbomgen.log_warn(message)	WARN	예
sbomgen.log_error(message)	오류	예

형식이 지정된 메시지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 인수는 테스트 파일의 디렉터리를 기준으로 확인됩니다.

함수	아티팩트 종류
testing.scan_directory(path)	디렉터리
testing.scan_archive(path)	디렉터리(의 별칭scan_directory)
testing.scan_localhost(path)	Localhost
testing.scan_binary(path)	바이너리
testing.scan_volume(path)	볼륨
testing.scan_container(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)

어설션

함수	Signature	설명
testing.assert_equals	(expected: any, actual: any, message?: string)	인 경우 실패합니다tostring(expected) ~= tostring(actual).
testing.assert_not_equals	(expected: any, actual: any, message?: string)	인 경우 실패합니다tostring(expected) == tostring(actual).
testing.assert_true	(value: any, message?: string)	이 false 또는 value인 경우 실패합니다nil.
testing.assert_false	(value: any, message?: string)	value이 아닌 경우 실패false하고이 아닌 경우 실패합니다nil.
testing.assert_nil	(value: any, message?: string)	이 value가 아닌 경우 실패합니다nil.
testing.assert_not_nil	(value: any, message?: string)	이 value인 경우 실패합니다nil.
testing.assert_contains	(haystack: string, needle: string, message?: string)	haystack에 needle (하위 문자열 일치)가 포함되어 있지 않으면 실패합니다.
testing.assert_matches	(str: string, pattern: string, message?: string)	str가 지정된 Go(RE2) 정규식과 일치하지 않으면 실패합니다.
testing.assert_length	(tbl: table, expected: integer, message?: string)	#tbl가와 같지 않으면 실패합니다expected.

제어 흐름

함수	Signature	설명
testing.fail	(message: string)	지정된 메시지와 함께 현재 테스트에 즉시 실패합니다.
testing.skip	(message: string)	현재 테스트를 건너뜁니다. 결과는 건너뛰고 실패하지 않은 것으로 보고됩니다.

테스트 검색

파일 일치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은 경고를 기록하고 다음 파일 또는 플러그인을 계속 진행합니다. 다른 플러그인은 영향을 받지 않습니다.